List Contacts

List all contacts for your organization. Each contact includes identifiers, contact_memories (per persona/agent), and memory entities. Paginated.

GET /v1/contacts

List Contacts

cURL

curl --request GET \
  --url https://api.bland.ai/v1/contacts \
  --header 'authorization: <authorization>'

Response

{
  "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": "[phone]",
          "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": "[phone]",
            "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).

Response

{
  "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": "[phone]",
          "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": "[phone]",
            "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
}