Get Contacts API

The Get Contacts API allows you to retrieve all contacts associated with your AI agent. Contacts include all users the agent has interacted with, as well as those manually uploaded or added via API.

API Endpoint

https://service.tailortalk.ai/api/v1/get_contacts

Headers

Key	Value
Authorization	Agent <token>

You can find agent_token in Manage Agent page.

Request Body

Parameter	Required	Description
start_after	❌	ISO 8601 timestamp - Get contacts created before this date (used for pagination)
limit	❌	Number of contacts to retrieve (max 500)

Example: Basic Request

{
    "start_after": "2026-08-03T17:30:05+00:00",
    "limit": 50
}

Example: Pagination

To paginate through contacts, use the created_at from the last contact in the previous response as start_after in the next request:

{
    "start_after": "2025-11-08T05:39:17+00:00",
    "limit": 50
}

This will fetch the next 50 contacts who were created before 2025-11-08T05:39:17+00:00.

Response Format

The API returns a JSON object with contact information. Custom attributes are automatically flattened into the object.

{
    "contacts": [
        {
            "name": "John Doe",
            "phone_number": "91********",
            "created_at": "2025-11-08T05:39:17+00:00",
            "updated_at": "2025-11-08T05:39:17+00:00",
            "city": "Mumbai",
            "membership": "Gold"
        },
        {
            "name": "Jane Smith",
            "phone_number": "91********",
            "created_at": "2025-10-23T10:26:29+00:00",
            "updated_at": "2025-10-23T10:26:29+00:00",
            "city": "Delhi"
        }
    ],
    "count": 2
}

Notes

• Ensure that the agent access token is included in the request headers
• Maximum limit per request is 500 contacts
• Pagination: Use the created_at from the last contact in the response as start_after in your next request to fetch older contacts
• All dates should be in ISO 8601 format with timezone (e.g., 2025-11-08T05:39:17+00:00)
• Custom attributes added via CSV or API will appear as top-level fields in the response.