Synchronize customer details, apply grouping tags, and store custom metadata parameters to coordinate campaigns. Custom fields are reactive and can be queried directly inside the Bot Flow Builder logic nodes.
Create a new contact card or update an existing contact dynamically if the phone number already exists.
POST /v1/contacts
| Parameter | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | Destination mobile number, formatted with country code prefix (e.g. 918856879188, no spaces or symbols). |
first_name | string | No | Customer's first name. |
last_name | string | No | Customer's last name. |
email | string | No | Valid email address. |
tags | array | No | List of grouping labels (e.g. ["VIP", "Lead"]). |
custom_fields | object | No | Key-value dictionary containing custom attributes (e.g. {"shopify_id": "cust_29813a"}). |
Fetch segmented lists of synced contacts, complete with pagination support.
GET /v1/contacts
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Number of records to return (Default: 20, Max: 100). |
offset | integer | No | Number of records to skip (for paging). |
tag | string | No | Filter contacts matching a specific tag parameter. |
200 OK){
"success": true,
"contacts": [
{
"id": "cnt_918856879188",
"phone": "918856879188",
"first_name": "Priya",
"last_name": "Sharma",
"email": "priya@example.com",
"tags": ["Lead"],
"created_at": "2026-06-02T08:00:00Z"
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0
}
}
# Create a new customer contact entry
curl -X POST "https://api.aisoule.com/v1/contacts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "918856879188",
"first_name": "Priya",
"last_name": "Sharma",
"email": "priya@example.com",
"tags": ["Lead", "High-Priority"],
"custom_fields": {
"shopify_id": "cust_29813a",
"acquisition_source": "AdWords"
}
}'