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

# Create Contact Memory

> Create a memory record for a contact scoped to a persona or agent number. If a record already exists for that pair, it is returned instead of creating a duplicate.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

**contact\_id** `string` *required*

The unique identifier of the contact.

**persona\_id** `string`

The persona ID for memory scoping. Either `persona_id` or `agent_number` is required.

**agent\_number** `string`

The agent phone number for memory scoping. Either `persona_id` or `agent_number` is required.

### Response

**data** `object`

Response containing the memory and creation status.

**data.memory** `object`

The contact memory object.

**data.memory.id** `string`

Unique identifier for the contact memory.

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

Organization ID this memory belongs to.

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

Contact ID this memory is associated with.

**data.memory.persona\_id** `string`

Persona ID this memory is scoped to (null if agent-based).

**data.memory.agent\_number** `string`

Agent phone number this memory is scoped to (null if persona-based).

**data.memory.summary** `string`

Rolling summary (empty for new memories).

**data.memory.facts** `object`

Structured facts (empty object for new memories).

**data.memory.recent\_messages** `array`

Recent messages array (empty for new memories).

**data.created** `boolean`

Whether a new memory was created (true) or an existing one was returned (false).

**errors** `null`

Error array (null on success).

```json New Memory Created theme={null}
{
  "data": {
    "memory": {
      "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "org_id": "11111111-2222-3333-4444-555555555555",
      "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "persona_id": "persona-12345678",
      "agent_number": null,
      "summary": null,
      "facts": {},
      "recent_messages": [],
      "open_items": [],
      "memory_history": [],
      "created_at": "2025-07-22T10:30:00.000Z",
      "updated_at": "2025-07-22T10:30:00.000Z"
    },
    "created": true
  },
  "errors": null
}
```

```json Existing Memory Found theme={null}
{
  "data": {
    "memory": {
      "id": "mem-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "org_id": "11111111-2222-3333-4444-555555555555",
      "contact_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "persona_id": "persona-12345678",
      "agent_number": null,
      "summary": "Customer called about order #8821 which was delayed. Promised a follow-up within 24 hours.",
      "facts": {
        "name": "Sarah Chen",
        "phone": "+14155550192",
        "preferred_contact": "phone"
      },
      "recent_messages": [
        {
          "role": "user",
          "content": "Hi, I'm calling about my order",
          "channel": "call",
          "timestamp": "2025-07-22T10:30:00.000Z"
        }
      ],
      "open_items": [
        {
          "type": "follow_up",
          "description": "Follow up on order #8821 delay status",
          "created_at": "2025-07-22T10:30:00.000Z",
          "priority": "high",
          "related_to": {
            "entity_type": "order",
            "entity_id": "order-8821"
          }
        }
      ],
      "memory_history": [],
      "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": "persona_id or agent_number 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.