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
# 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.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);
});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
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
# 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": "[email protected]",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata"
}'
# Please replace YOUR_API_KEY and verify the request data before execution.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": "[email protected]",
"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);
});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": "[email protected]",
"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
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": "[email protected]",
"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": "[email protected]",
"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
# 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.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);
});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
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": "[email protected]",
"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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}Code Examples
# 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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}'
# Please replace YOUR_API_KEY and verify the request data before execution.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": "[email protected]",
"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);
});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": "[email protected]",
"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
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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}Code Examples
# 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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}'
# Please replace YOUR_API_KEY and verify the request data before execution.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": "[email protected]",
"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);
});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": "[email protected]",
"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
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": "[email protected]",
"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": "[email protected]",
"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
# 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.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);
});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
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
Last updated
Was this helpful?