Skip to main content
GET
https://api.bland.ai
/
v1
/
contacts
List Contacts
curl --request GET \
  --url https://api.bland.ai/v1/contacts \
  --header 'authorization: <authorization>'
{
  "data": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "org_id": "11111111-2222-3333-4444-555555555555",
      "name": "John Doe",
      "metadata": {},
      "created_at": "2025-07-20T10:30:00.000Z",
      "updated_at": "2025-07-22T15:45:00.000Z",
      "identifiers": [
        {
          "id": "...",
          "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "identifier_type": "phone_number",
          "identifier_value": "+15551234567",
          "is_primary": true
        }
      ],
      "memories": [
        {
          "id": "...",
          "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "persona_id": null,
          "agent_number": "+15559876543",
          "summary": "Customer prefers morning calls.",
          "facts": {},
          "entities": []
        }
      ]
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "errors": null
}

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Query Parameters

​
limit
integer
Maximum number of contacts to return. Default 50, max 200.
​
offset
integer
Number of contacts to skip (for pagination). Default 0.

​
Response

​
data
array
Array of contact objects. Each includes identifiers, memories (with entities).
​
pagination
object
Pagination metadata (total, limit, offset, has_more).
​
pagination.total
integer
Total number of contacts in the org.
​
pagination.limit
integer
Limit used for this request.
​
pagination.offset
integer
Offset used for this request.
​
pagination.has_more
boolean
Whether more contacts exist after this page.
​
errors
null
Error array (null on success).
{
  "data": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "org_id": "11111111-2222-3333-4444-555555555555",
      "name": "John Doe",
      "metadata": {},
      "created_at": "2025-07-20T10:30:00.000Z",
      "updated_at": "2025-07-22T15:45:00.000Z",
      "identifiers": [
        {
          "id": "...",
          "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "identifier_type": "phone_number",
          "identifier_value": "+15551234567",
          "is_primary": true
        }
      ],
      "memories": [
        {
          "id": "...",
          "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "persona_id": null,
          "agent_number": "+15559876543",
          "summary": "Customer prefers morning calls.",
          "facts": {},
          "entities": []
        }
      ]
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "errors": null
}