Contacts

List Contacts

GET /api/contacts/

Parameters

Parameter Name	Required	Type	Description
inbox	❌	string	Deprecated: Use inboxes instead
inboxes	❌	string	Conversation platform ID (used to filter contacts from a specific inbox)
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string	Search by name or source ID
search	❌	string	Full-text search

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example", config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Successfully retrieved response:")
    print(response.json())
except Exception as e:
    print("An error occurred with the request:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully got response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "inboxes"?: [ // Optional
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "inbox"?:  // Backward compatibility field: single inbox, ignored if inboxes is also provided (Optional)
      {
        "id": string (uuid)
        "name": string
      }
      "name": string
      "avatar"?: string (uri) // Optional
      "phoneNumber"?: string // Optional
      "email"?: string (email) // Optional
      "sourceId"?: string // Optional
      "queryMetadata"?: object // Optional
      "mcpCredentials": string // List of the contact's MCP credentials
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}

Response Example Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    [
      {
        "id": "user1_uuid",
        "inboxes": [
          {
            "id": "inbox_uuid",
            "name": "inbox_name"
          }
        ],
        "name": "user1",
        "avatar": "",
        "sourceId": null,
        "queryMetadata": null,
        "createdAt": "1751875361000",
        "updatedAt": "1751875361000"
      },
      {
        "id": "user2_uuid",
        "inboxes": [
          {
            "id": "inbox_uuid",
            "name": "inbox_name"
          }
        ],
        "name": "user2",
        "avatar": "avatar_url",
        "sourceId": "self defined source id",
        "queryMetadata": "self defined query metadata",
        "createdAt": "1751875400000",
        "updatedAt": "1751875400000"
      }
    ]
  ]
}

---

Create Contact

POST /api/contacts/

Code Example

Shell/Bash

# API Call Example (Shell)
curl -X POST "https://api.maiagent.ai/api/contacts/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxes": [
      {
        "id": "inbox_uuid"
      }
    ],
    "name": "user1",
    "avatar": "",
    "phoneNumber": 912345678,
    "email": "[e-mail]",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata"
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request payload
const data = {
    "inboxes": [
      {
        "id": "inbox_uuid"
      }
    ],
    "name": "user1",
    "avatar": "",
    "phoneNumber": 912345678,
    "email": "[e-mail]",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata"
  };

axios.post("https://api.maiagent.ai/api/contacts/", data, config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request payload
data = {
      "inboxes": [
        {
          "id": "inbox_uuid"
        }
      ],
      "name": "user1",
      "avatar": "",
      "phoneNumber": 912345678,
      "email": "[e-mail]",
      "sourceId": "self defined source id",
      "queryMetadata": "self defined query metadata"
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("Successfully received response:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/contacts/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "inboxes": [
                {
                    "id": "inbox_uuid"
                }
            ],
            "name": "user1",
            "avatar": "",
            "phoneNumber": 912345678,
            "email": "[e-mail]",
            "sourceId": "self defined source id",
            "queryMetadata": "self defined query metadata"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully got response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code: 201

Response Schema Example

{
  "id": string (uuid)
  "inboxes"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "inbox"?:  // Backward compatibility field: single inbox, ignored if inboxes is also provided (Optional)
  {
    "id": string (uuid)
    "name": string
  }
  "name": string
  "avatar"?: string (uri) // Optional
  "phoneNumber"?: string // Optional
  "email"?: string (email) // Optional
  "sourceId"?: string // Optional
  "queryMetadata"?: object // Optional
  "mcpCredentials": string // List of the contact's MCP credentials
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

Response Example Value

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

Get Contact Details

GET /api/contacts/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Contact.

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Successfully retrieved response:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully got response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "inboxes"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "inbox"?:  // Backward compatibility field: single inbox, ignored if inboxes is also provided (Optional)
  {
    "id": string (uuid)
    "name": string
  }
  "name": string
  "avatar"?: string (uri) // Optional
  "phoneNumber"?: string // Optional
  "email"?: string (email) // Optional
  "sourceId"?: string // Optional
  "queryMetadata"?: object // Optional
  "mcpCredentials": string // List of the contact's MCP credentials
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

Response Example Value

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

Update Contact

PUT /api/contacts/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Contact.

Request Body

Request Parameters

Field	Type	Required	Description
name	string	No	Contact name
inboxes	array[object]	No	List of inboxes (new format)
inbox	object	No	Single inbox (old format, for backward compatibility)
inbox.id	string (uuid)	Yes	Inbox ID
avatar	string	No	Avatar URL
sourceId	string	No	Source ID
queryMetadata	string	No	Query metadata

Request Structure Example

{
  "name"?: string // Contact name (optional)
  "inboxes"?: [ // List of inboxes (new format) (optional)
    {
      "id": string (uuid) // Inbox ID
    }
  ]
  "inbox"?: { // Single inbox (old format, for backward compatibility) (optional)
  {
    "id": string (uuid) // Inbox ID
  }
  }
  "avatar"?: string // Avatar URL (optional)
  "sourceId"?: string // Source ID (optional)
  "queryMetadata"?: string // Query metadata (optional)
}

Request Example Value

{
  "inboxes": [
    {
      "id": "new_inbox_uuid"
    }
  ],
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "phoneNumber": 987654321,
  "email": "[e-mail]",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata"
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PUT "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxes": [
      {
        "id": "new_inbox_uuid"
      }
    ],
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "phoneNumber": 987654321,
    "email": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata"
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request payload
const data = {
    "inboxes": [
      {
        "id": "new_inbox_uuid"
      }
    ],
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "phoneNumber": 987654321,
    "email": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata"
  };

axios.put("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request payload
data = {
      "inboxes": [
        {
          "id": "new_inbox_uuid"
        }
      ],
      "name": "updated_user_name",
      "avatar": "updated_avatar_url",
      "phoneNumber": 987654321,
      "email": "[e-mail]",
      "sourceId": "updated_source_id",
      "queryMetadata": "updated_query_metadata"
    }

response = requests.put(url, json=data, headers=headers)
try:
    print("Successfully received response:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "inboxes": [
                {
                    "id": "new_inbox_uuid"
                }
            ],
            "name": "updated_user_name",
            "avatar": "updated_avatar_url",
            "phoneNumber": 987654321,
            "email": "[e-mail]",
            "sourceId": "updated_source_id",
            "queryMetadata": "updated_query_metadata"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Error during request: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "inboxes"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "inbox"?:  // Backward compatibility field: single inbox, ignored if inboxes is also provided (Optional)
  {
    "id": string (uuid)
    "name": string
  }
  "name": string
  "avatar"?: string (uri) // Optional
  "phoneNumber"?: string // Optional
  "email"?: string (email) // Optional
  "sourceId"?: string // Optional
  "queryMetadata"?: object // Optional
  "mcpCredentials": string // List of the contact's MCP credentials
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

Response Example Value

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

Update Contact

PATCH /api/contacts/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Contact.

Request Body

Request Parameters

Field	Type	Required	Description
name	string	No	Contact name
inboxes	array[object]	No	List of inboxes (new format)
inbox	object	No	Single inbox (old format, for backward compatibility)
inbox.id	string (uuid)	Yes	Inbox ID
avatar	string	No	Avatar URL
sourceId	string	No	Source ID
queryMetadata	string	No	Query metadata

Request Structure Example

{
  "name"?: string // Contact name (optional)
  "inboxes"?: [ // List of inboxes (new format) (optional)
    {
      "id": string (uuid) // Inbox ID
    }
  ]
  "inbox"?: { // Single inbox (old format, for backward compatibility) (optional)
  {
    "id": string (uuid) // Inbox ID
  }
  }
  "avatar"?: string // Avatar URL (optional)
  "sourceId"?: string // Source ID (optional)
  "queryMetadata"?: string // Query metadata (optional)
}

Request Example Value

{
  "inboxes": [
    {
      "id": "new_inbox_uuid"
    }
  ],
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "phoneNumber": 987654321,
  "email": "[e-mail]",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata"
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxes": [
      {
        "id": "new_inbox_uuid"
      }
    ],
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "phoneNumber": 987654321,
    "email": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata"
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request payload
const data = {
    "inboxes": [
      {
        "id": "new_inbox_uuid"
      }
    ],
    "name": "updated_user_name",
    "avatar": "updated_avatar_url",
    "phoneNumber": 987654321,
    "email": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata"
  };

axios.patch("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request payload
data = {
      "inboxes": [
        {
          "id": "new_inbox_uuid"
        }
      ],
      "name": "updated_user_name",
      "avatar": "updated_avatar_url",
      "phoneNumber": 987654321,
      "email": "[e-mail]",
      "sourceId": "updated_source_id",
      "queryMetadata": "updated_query_metadata"
    }

response = requests.patch(url, json=data, headers=headers)
try:
    print("Successfully got response:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "inboxes": [
                {
                    "id": "new_inbox_uuid"
                }
            ],
            "name": "updated_user_name",
            "avatar": "updated_avatar_url",
            "phoneNumber": 987654321,
            "email": "[e-mail]",
            "sourceId": "updated_source_id",
            "queryMetadata": "updated_query_metadata"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred with the request: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "inboxes"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "inbox"?:  // Backward compatibility field: single inbox, ignored if inboxes is also provided (Optional)
  {
    "id": string (uuid)
    "name": string
  }
  "name": string
  "avatar"?: string (uri) // Optional
  "phoneNumber"?: string // Optional
  "email"?: string (email) // Optional
  "sourceId"?: string // Optional
  "queryMetadata"?: object // Optional
  "mcpCredentials": string // List of the contact's MCP credentials
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

Response Example Value

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

Delete Contact

DELETE /api/contacts/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Contact.

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request payload
const data = null;

axios.delete("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("Successfully received response:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>

Response

Status Code	Description
204	No response body
400	The contact still has associated conversations and cannot be deleted

---