Skip to main content
GET
/
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": "Sarah Chen",
      "metadata": {
        "source": "inbound_call"
      },
      "created_at": "2025-07-20T10:30:00.000Z",
      "updated_at": "2025-07-23T09:15:00.000Z",
      "identifiers": [
        {
          "id": "ident-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",
          "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "identifier_type": "phone_number",
          "identifier_value": "+14155550192",
          "is_primary": true
        }
      ],
      "memories": [
        {
          "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "persona_id": "persona-12345678",
          "agent_number": null,
          "summary": "Customer called about order #8821 which was delayed. Follow-up SMS confirmed the order shipped and is now in transit. Expected delivery July 25.",
          "facts": {
            "name": "Sarah Chen",
            "phone": "+14155550192",
            "preferred_contact": "sms",
            "timezone": "America/Los_Angeles"
          },
          "recent_messages": [
            {
              "role": "user",
              "content": "Has my order shipped yet?",
              "channel": "sms",
              "timestamp": "2025-07-23T09:10:00.000Z"
            },
            {
              "role": "assistant",
              "content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.",
              "channel": "sms",
              "timestamp": "2025-07-23T09:10:05.000Z"
            }
          ],
          "open_items": [
            {
              "type": "follow_up",
              "description": "Confirm delivery of order #8821 on July 25",
              "created_at": "2025-07-23T09:10:00.000Z",
              "priority": "medium",
              "related_to": {
                "entity_type": "order",
                "entity_id": "order-8821"
              }
            }
          ],
          "entities": [
            {
              "entity_type": "order",
              "entity_id": "order-8821",
              "facts": {
                "order_number": "#8821",
                "status": "in_transit",
                "carrier": "UPS",
                "expected_delivery": "2025-07-25"
              },
              "status": "in_transit",
              "last_discussed_at": "2025-07-23T09:10:00.000Z",
              "notes": null
            }
          ]
        }
      ]
    }
  ],
  "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": "Sarah Chen",
      "metadata": {
        "source": "inbound_call"
      },
      "created_at": "2025-07-20T10:30:00.000Z",
      "updated_at": "2025-07-23T09:15:00.000Z",
      "identifiers": [
        {
          "id": "ident-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",
          "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "identifier_type": "phone_number",
          "identifier_value": "+14155550192",
          "is_primary": true
        }
      ],
      "memories": [
        {
          "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "persona_id": "persona-12345678",
          "agent_number": null,
          "summary": "Customer called about order #8821 which was delayed. Follow-up SMS confirmed the order shipped and is now in transit. Expected delivery July 25.",
          "facts": {
            "name": "Sarah Chen",
            "phone": "+14155550192",
            "preferred_contact": "sms",
            "timezone": "America/Los_Angeles"
          },
          "recent_messages": [
            {
              "role": "user",
              "content": "Has my order shipped yet?",
              "channel": "sms",
              "timestamp": "2025-07-23T09:10:00.000Z"
            },
            {
              "role": "assistant",
              "content": "Yes, order #8821 shipped this morning. Expected delivery is Friday July 25.",
              "channel": "sms",
              "timestamp": "2025-07-23T09:10:05.000Z"
            }
          ],
          "open_items": [
            {
              "type": "follow_up",
              "description": "Confirm delivery of order #8821 on July 25",
              "created_at": "2025-07-23T09:10:00.000Z",
              "priority": "medium",
              "related_to": {
                "entity_type": "order",
                "entity_id": "order-8821"
              }
            }
          ],
          "entities": [
            {
              "entity_type": "order",
              "entity_id": "order-8821",
              "facts": {
                "order_number": "#8821",
                "status": "in_transit",
                "carrier": "UPS",
                "expected_delivery": "2025-07-25"
              },
              "status": "in_transit",
              "last_discussed_at": "2025-07-23T09:10:00.000Z",
              "notes": null
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "errors": null
}
Docs for agents: llms.txt