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

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

### Body Parameters

<ParamField body="contact_id" type="string" required>
  The unique identifier of the contact.
</ParamField>

<ParamField body="persona_id" type="string">
  The persona ID for memory scoping. Either `persona_id` or `agent_number` is required.
</ParamField>

<ParamField body="agent_number" type="string">
  The agent phone number for memory scoping. Either `persona_id` or `agent_number` is required.
</ParamField>

### Response

<ResponseField name="data" type="object">
  Response containing the memory and creation status.
</ResponseField>

<ResponseField name="data.memory" type="object">
  The contact memory object.
</ResponseField>

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

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

<ResponseField name="data.memory.contact_id" type="string">
  Contact ID this memory is associated with.
</ResponseField>

<ResponseField name="data.memory.persona_id" type="string">
  Persona ID this memory is scoped to (null if agent-based).
</ResponseField>

<ResponseField name="data.memory.agent_number" type="string">
  Agent phone number this memory is scoped to (null if persona-based).
</ResponseField>

<ResponseField name="data.memory.summary" type="string">
  Rolling summary (empty for new memories).
</ResponseField>

<ResponseField name="data.memory.facts" type="object">
  Structured facts (empty object for new memories).
</ResponseField>

<ResponseField name="data.memory.recent_messages" type="array">
  Recent messages array (empty for new memories).
</ResponseField>

<ResponseField name="data.created" type="boolean">
  Whether a new memory was created (true) or an existing one was returned (false).
</ResponseField>

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

<ResponseExample>
  ```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"
      }
    ]
  }
  ```
</ResponseExample>

***

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