> ## 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.

# Resolve Contact

> Find an existing contact or create a new one.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

**phone\_number** `string`

Phone number for the contact. At least one identifier is required.

**email** `string`

Email address for the contact. At least one identifier is required.

**external\_id** `string`

External ID for the contact. At least one identifier is required.

**name** `string`

Name of the contact.

**persona\_id** `string`

Persona ID for memory scoping. Either `persona_id` or `agent_number` should be provided for memory creation.

**agent\_number** `string`

Agent phone number for memory scoping. Either `persona_id` or `agent_number` should be provided for memory creation.

**metadata** `object`

Custom metadata to associate with the contact.

### Response

**data** `object`

Response containing the contact and creation status.

**data.contact** `object`

The resolved contact object.

**data.contact.id** `string`

Unique identifier for the contact.

**data.contact.org\_id** `string`

Organization ID the contact belongs to.

**data.contact.name** `string`

Contact's name (if set).

**data.contact.metadata** `object`

Custom metadata associated with the contact.

**data.contact.created\_at** `string`

ISO timestamp when the contact was created.

**data.contact.updated\_at** `string`

ISO timestamp when the contact was last updated.

**data.created** `boolean`

Whether a new contact was created (true) or an existing one was found (false).

**errors** `null`

Error array (null on success).

```json New Contact Created theme={null}
{
  "data": {
    "contact": {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "org_id": "11111111-2222-3333-4444-555555555555",
      "name": "John Doe",
      "metadata": {
        "source": "api"
      },
      "created_at": "2025-07-22T10:30:00.000Z",
      "updated_at": "2025-07-22T10:30:00.000Z"
    },
    "created": true
  },
  "errors": null
}
```

```json Existing Contact Found theme={null}
{
  "data": {
    "contact": {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "org_id": "11111111-2222-3333-4444-555555555555",
      "name": "John Doe",
      "metadata": {
        "source": "web_signup"
      },
      "created_at": "2025-07-20T10:30:00.000Z",
      "updated_at": "2025-07-22T15:45:00.000Z"
    },
    "created": false
  },
  "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"
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.