# Contact variables

These methods read, write and delete [contact variables](https://support.watbot.org/chatbots/contacts/tags-variables#contact-variables) — the same ones the bot fills in during a scenario and shows on the contact card. For example, your website can save an order number to a variable, and the bot can insert it into a message as `{{ $order_number }}` (see [Templates](https://support.watbot.org/chatbots/templates) for details).

The contact ID (`contact_id`) is shown in the header of the [contact card](https://support.watbot.org/chatbots/contacts/card) and in the first column of the contact list.

## getContactVariables

Returns all variables of a contact.

```endpoint
GET POST https://watbot.org/api/v1/getContactVariables
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | integer | yes | Contact ID |

```bash title="Request"
curl -X POST "https://watbot.org/api/v1/getContactVariables" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678}'
```
```json title="Response 200"
{
  "data": [
    {
      "id": 17594321098765,
      "name": "city",
      "value": "Denver",
      "deletable": false,
      "variable": {
        "id": 17594321098765,
        "name": "Denver"
      }
    },
    {
      "id": 17594321112233,
      "name": "order_number",
      "value": "A-1024",
      "deletable": false,
      "variable": {
        "id": 17594321112233,
        "name": "A-1024"
      }
    }
  ]
}
```

| Field | Description |
|---|---|
| `id` | ID of the variable for this contact |
| `name` | Variable name |
| `value` | Value |
| `deletable` | `true` — the variable is deleted after the [Request](https://support.watbot.org/chatbots/blocks/notifications/notification) block is sent |
| `variable` | Legacy field for old integrations: `id` is the variable ID, `name` is its **value**. Do not use it in new code |

Variables are listed in the order they were created. If there are none, `data` is an empty array.

## setContactVariable

Writes a value to a contact variable. If there is no variable with this name, it is created; if there is, its value is replaced.

```endpoint
POST https://watbot.org/api/v1/setContactVariable
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | integer | yes | Contact ID |
| `name` | string | yes | Variable name, up to 255 characters: letters, digits, `_` and spaces |
| `value` | string | yes | Value, up to 4096 characters. Pass numbers as strings: `"150"`, not `150` |
| `deletable` | `0` or `1` | no | `1` — delete the variable after the Request block is sent. Defaults to `0` |

```bash title="Request"
curl -X POST "https://watbot.org/api/v1/setContactVariable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "order_number", "value": "A-1024"}'
```
```json title="Response 200"
{
  "data": {
    "id": 17594321112233,
    "name": "order_number",
    "value": "A-1024",
    "deletable": false,
    "variable": {
      "id": 17594321112233,
      "name": "A-1024"
    }
  }
}
```
```json title="Response 422"
{
  "message": "The contact already has 5000 variables — a new one cannot be added.",
  "error": "The contact already has 5000 variables — a new one cannot be added.",
  "code": "variables_limit",
  "errors": {
    "name": ["The contact already has 5000 variables — a new one cannot be added."]
  }
}
```

Details:

- You cannot write an empty value: `value` is required. To clear a variable, delete it with `deleteContactVariable`.
- When you write to an existing variable, `deletable` is overwritten too: if the parameter is omitted, it becomes `false`.
- The name of a new variable is added to the bot's "User variable hints" list, so it appears in the account's suggestions and in the [contact export](https://support.watbot.org/chatbots/contacts/import-export). If the list already holds 5000 names, the new name is not added to it, but the contact's variable is still written.
- A contact can have at most 5000 variables. Beyond that the method does not create a new one and responds with `422` and `code: "variables_limit"`. Writing to an existing variable always works.
- Contact not found, deleted, or its bot deleted — `404`; contact from someone else's bot — `403`.

## deleteContactVariable

Deletes a contact variable by ID or by name.

```endpoint
POST https://watbot.org/api/v1/deleteContactVariable
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | integer | yes | Contact ID |
| `id` | integer | if `name` is missing | Variable ID from `getContactVariables` |
| `name` | string | if `id` is missing | Variable name, up to 255 characters |

If both are passed, `name` is used; if there is no variable with that name, `id` is used.

```bash title="Request"
curl -X POST "https://watbot.org/api/v1/deleteContactVariable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "name": "order_number"}'
```

The response is status `204` with no body.

Details:

- If the contact has no such variable, the method still responds with `204`.
- The name is not removed from the bot's hint list.
- Contact not found, deleted, or its bot deleted — `404`; contact from someone else's bot — `403`.

General API errors are described under [Errors](https://support.watbot.org/api#errors).