> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Contact

> Find a contact by phone number, email, or external ID. Returns the contact with all identifiers, contact_memories (per persona/agent), and memory entities.

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Body Parameters

<ParamField body="phone_number" type="string">
  Phone number to search for. At least one identifier is required.
</ParamField>

<ParamField body="email" type="string">
  Email address to search for. At least one identifier is required.
</ParamField>

<ParamField body="external_id" type="string">
  External ID to search for. At least one identifier is required.
</ParamField>

### Response

Returns the contact with related data, or `null` if not found.

<ResponseField name="data" type="object">
  The contact object with identifiers, memories, and entities. Null if no contact found.
</ResponseField>

<ResponseField name="data.id" type="string">
  Unique identifier for the contact.
</ResponseField>

<ResponseField name="data.org_id" type="string">
  Organization ID the contact belongs to.
</ResponseField>

<ResponseField name="data.name" type="string">
  Contact's name (if set).
</ResponseField>

<ResponseField name="data.metadata" type="object">
  Custom metadata associated with the contact.
</ResponseField>

<ResponseField name="data.identifiers" type="array">
  Contact identifiers (phone\_number, email, external\_id) for this contact.
</ResponseField>

<ResponseField name="data.memories" type="array">
  Contact memory objects, one per persona or agent. Each includes summary, facts, recent\_messages, open\_items, and entities (memory\_entity records).
</ResponseField>

<ResponseField name="data.memories[].entities" type="array">
  Entity-scoped facts (e.g. bookings, orders) for that memory.
</ResponseField>

<ResponseField name="errors" type="null">
  Error array (null on success).
</ResponseField>

<ResponseExample>
  ```json Response (found) theme={null}
  {
    "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
            }
          ]
        }
      ]
    },
    "errors": null
  }
  ```

  ```json Not Found theme={null}
  {
    "data": null,
    "errors": null
  }
  ```

  ```json Error Response theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "BAD_REQUEST",
        "message": "At least one identifier (phone_number, email, or external_id) is required"
      }
    ]
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)