> For the complete documentation index, see [llms.txt](https://docs.graspil.com/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/ru/api/custom-fields.md).

# Доп. поля пользователей

## Создание доп. поля

<mark style="color:green;">`POST`</mark> `/v1/custom-fields/create`

Заводит новое доп. поле у ресурса — то же самое, что создание поля в личном кабинете (раздел «Доп. поля»). После создания поле сразу доступно:

* в конструкторе автоматизаций — как `user.custom_fields.<key>` (чтение в условии, запись — узлом «Изменить доп. поле»);
* в отчётах — как поле для сегментации.

Чтобы заполнить значение поля у конкретных пользователей, используйте метод ниже — «Отправка данных в доп. поле».

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| Api-Key      | `<token>`          |

**Body**

| Name           | Type   | Обязательный                                    | Описание                                                                                                               |
| -------------- | ------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `resource_key` | string | только для ключей с доступом к нескольким ботам | Целевой ресурс                                                                                                         |
| `name`         | string | да                                              | Название поля, отображается в личном кабинете                                                                          |
| `key`          | string | да                                              | Машинный ключ: буквы, цифры, `_`, `-`. Используется как `user.custom_fields.<key>`. **Нельзя изменить после создания** |
| `type`         | string | да                                              | `number` \| `string` \| `date` \| `array` \| `bool`. **Нельзя изменить после создания**                                |
| `settings`     | object | нет                                             | Произвольные настройки поля                                                                                            |

{% hint style="warning" %}
`key` и `type` неизменяемы после создания — если ошибиться, придётся создавать новое поле под другим ключом.
{% endhint %}

**Request (пример)**

```json
POST /v1/custom-fields/create
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "name": "Статус подписки",
  "key": "subscription_status",
  "type": "string"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true,
  "data": {
    "key": "subscription_status",
    "name": "Статус подписки",
    "type": "string",
    "settings": null,
    "is_system": false,
    "resource_key": "abc123..."
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "ok": false,
  "error": { "errors": { "key": ["Key has already been taken"] } }
}
```

{% endtab %}
{% endtabs %}

***

## Отправка данных в доп. поле

<mark style="color:green;">`POST`</mark> `/v1/send-user-field`

Данным методом можно заполнить или обновить сразу несколько разных полей у разных пользователей

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| Api-Key      | `<token>`          |

**Body**

Передайте массив объектов с данными:

| Name      | Type                                | Description                                                                                                                                                                                                                 |
| --------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`     | string                              | Уникальный ключ поля                                                                                                                                                                                                        |
| `value`   | String \| Number \| Boolean \| Date | Значение. Должно быть типа соответствующему типу поля. Дата может быть в формате `Unixtime`, `ISO8601`, `Y-m-d H:i:s`                                                                                                       |
| `user_id` | Integer или String                  | Пользователь, которому принадлежит поле. Для telegram-ботов/каналов — числовой Telegram ID. Для [кастомных ботов и MAX](https://docs.graspil.com/ru/api/custom-bots.md) — строкой, тот же идентификатор, что и в сообщениях |

{% hint style="info" %}
Валидация типа данных происходит позже при обработке данных. При передачи валидируются только базовые показатели. Все ошибки возникшие на поздних этапах обработки попадают в раздел **ошибок ресурса**
{% endhint %}

**Request (пример)**

```
[
  {
    "key": "tariff",
    "value": 2,
    "user_id": 123123123
  }
]
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ok": true,
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "ok": false,
    "error_code": 400,
    "description": "Wrong json"
}
```

{% endtab %}
{% endtabs %}
