Custom fields
Custom fields are the company's catalog of fields stored on the contact card and on the conversation card (city, order number, deadline, inquiry reason). This section covers the catalog itself and writing values; values come back in contact and conversation responses in the `custom_fields` object.
Field types
The type (type) is set on creation and never changes afterwards. The value in requests and responses (custom_fields) looks like this:
| Type | Value |
|---|---|
string | A string of up to 1000 characters. |
textarea | Multi-line text of up to 10,000 characters. In the contact list it is cut to 500 characters (see custom_fields_truncated in the contacts group). |
number | A number (at most 14 digits before the point and 6 after); send it as a number or a string, the response carries the canonical form without trailing zeros. settings.decimals (0-6) is only a display hint. |
date | A YYYY-MM-DD string. |
select | The key of one option from options[].key. An archived option cannot be chosen (archived_option). |
multiselect | An array of option keys, at most 50, no duplicates. |
checkbox | true or false. |
url | An http:// or https:// address of up to 1000 characters. |
phone | A phone number; stored and returned in international E.164 format. A national number is read using the company's country. |
email | An email address of up to 254 characters. |
Field key
key is lowercase Latin letters, digits and _, starting with a letter, 2 to 64 characters. If omitted the server derives it from the label. The key is unique among the fields of one entity type (contact, conversation or organization) in the company, archived ones included, and never changes: scenarios, segments and the API refer to it. Option keys (options[].key) may also be omitted and are generated.
Permissions
- Reading the catalog (
GET /custom-fields):contact.viewforentity_type=contactand fororganization,conversation.viewforconversation. Archived fields (include_archived=1) are visible only to a holder ofcustom_field.manage. - Create, edit, reorder, archive, restore,
usages:custom_field.manage(administrator and manager). - Permanent delete (
DELETE):custom_field.delete(administrator only). - Writing a contact's values (
PUT /contacts/{contact}/custom-fields):custom_field_value.updateorcontact.update; a conversation's values:conversation.update; an organization's values (PUT /organizations/{organization}/custom-fields):organization.view,organization.updateandcustom_field_value.updatetogether. An agent withoutcontact.updatemay still fill in contact fields. - Without the permission the response is
403for any id; a foreign field or card is404. Embed widget tokens may read the catalog and write values but cannot change the catalog itself.
Limits
- At most 100 active fields per company, separately for contacts, for conversations and for organizations; exceeding it is
422withcustom_field_limit_reached(the same applies to restoring from the archive). - At most 200 options on a
select/multiselectfield; label and option label up to 100 characters, description up to 500. - The total size of all values on one card is at most 32,768 bytes, otherwise
422withcustom_fields_total_too_large. - Rate: catalog reads 60 per minute, catalog writes 20 per minute per user; value writes 120 per minute per user (an API token has its own separate counter). Exceeding it is
429. - Writing values is not available to non-business companies (for example Kids).
Errors
Validation errors arrive as 422 shaped {"data": {"message", "errors": {field: [code]}}}, where the code is a machine name. Catalog: label_required, label_too_long, description_too_long, invalid_key, key_taken, too_many_options, options_required, options_not_allowed, option_label_required, option_label_too_long, invalid_option_key, duplicate_option_label, duplicate_option_key, invalid_decimals, immutable (an attempt to change type, key or entity_type; re-sending the stored value is tolerated), ids_mismatch (reorder), custom_field_limit_reached. Values (path custom_fields.<key>): unknown_field (no such field or it is archived), invalid_type, invalid_format, too_long, too_many_values, unknown_option, archived_option; for the whole object, custom_fields_total_too_large. Re-sending an already stored value is not an error, even if its option was archived since.
Archive and delete
A field goes to the archive first: it disappears from responses, filters and pickers, values on contacts are kept, and the field can be restored (restore). If the field is used in scenarios, segments, AI employees or broadcasts, archiving without confirm: true answers 409 with message: "custom_field_in_use" and a usages list; with confirm: true the field is archived and the listed places stop using it. Only an archived field that is used nowhere can be deleted permanently, otherwise 409 (custom_field_not_archived or custom_field_in_use). Deletion is queued (202, custom_field_delete_queued) and wipes the values on every card; it cannot be undone. Archive, restore and delete are written to the audit log. GET /custom-fields/{id}/usages returns {automations, segments, ai_agents, broadcasts}: a scenario is {id, name, version_id}, a segment and an AI employee are {id, name}, a broadcast is {id, name, status}.
Writing values
The body of PUT .../custom-fields is only {"custom_fields": {"<key>": value}}, 1 to 100 keys. The write is partial: sent keys are set, null (or an empty string, empty array) clears the value, unsent keys stay as they were. Any error rolls back the whole write. Contact and conversation columns (status, first_name and so on) in this body are ignored. The same values can be passed in custom_fields on POST /contacts, PATCH /contacts/{id} and PATCH /conversations/{id}. The write source (source: manual, api, automation, ai, import, merge, mcp) is set by the server: a write from the cabinet and the mobile app is manual, with an API token it is api.
Organization fields
Since 2026-11-17 the catalog also covers CRM organizations: entity_type=organization in GET/POST /custom-fields and PUT /custom-fields/order. Values come in the organization custom_fields (the list, the card, the organization.* webhooks), are filtered and sorted in GET /organizations the same way as for contacts, and are written via PUT /organizations/{organization}/custom-fields. Scenarios, segments, AI employees, voice agents and broadcasts do not use organization fields yet, so the usages of such a field is always empty.
Events
Catalog changes arrive as webhooks of the Custom fields group: custom_field.created, custom_field.updated (with the changes list), custom_field.archived, custom_field.restored and custom_field.deleted (once the field is really gone). Reordering fields sends no events. Value changes on the cards arrive in contact.updated, conversation.updated and organization.updated.
Endpoints
| Method | Path | Summary |
|---|---|---|
| GET | /v1/custom-fieldsThe field catalog (query: entity_type = contact|conversation|organization — required; include_archived = 1 — with archived ones, needs custom_field.manage). Response: data.items. | The field catalog (query: entity_type = contact|conversation|organization — required; include_archived = 1 — with archived ones, needs custom_field.manage). Response: data.items. |
| POST | /v1/custom-fieldsCreate a field (body: entity_type, type, label, key?, description?, options[]?, settings?, is_ai_readable?) — 201, data.custom_field. The field is appended to the end of the list. | Create a field (body: entity_type, type, label, key?, description?, options[]?, settings?, is_ai_readable?) — 201, data.custom_field. The field is appended to the end of the list. |
| PATCH | /v1/custom-fields/{customField}Edit a field (label, description, options[], settings, is_ai_readable, position). type, key and entity_type are immutable (422 immutable). Options are sent as a whole: an option missing from the list is archived, not deleted. | Edit a field (label, description, options[], settings, is_ai_readable, position). type, key and entity_type are immutable (422 immutable). Options are sent as a whole: an option missing from the list is archived, not deleted. |
| PUT | /v1/custom-fields/orderSet the field order (body: entity_type, ids[] — exactly all active fields of that entity type, otherwise 422 ids_mismatch). Response: data.items. | Set the field order (body: entity_type, ids[] — exactly all active fields of that entity type, otherwise 422 ids_mismatch). Response: data.items. |
| POST | /v1/custom-fields/{customField}/archiveArchive a field (body: confirm?). 409 custom_field_in_use with a usages list if the field is in use and confirm is not sent. | Archive a field (body: confirm?). 409 custom_field_in_use with a usages list if the field is in use and confirm is not sent. |
| POST | /v1/custom-fields/{customField}/restoreRestore a field from the archive (422 custom_field_limit_reached if there are already 100 active fields). | Restore a field from the archive (422 custom_field_limit_reached if there are already 100 active fields). |
| GET | /v1/custom-fields/{customField}/usagesWhere the field is used: scenarios, segments, AI employees, broadcasts. | Where the field is used: scenarios, segments, AI employees, broadcasts. |
| DELETE | /v1/custom-fields/{customField}Permanently delete an archived field with all its values (custom_field.delete) — 202; 409 if the field is not archived or still in use. | Permanently delete an archived field with all its values (custom_field.delete) — 202; 409 if the field is not archived or still in use. |
| PUT | /v1/contacts/{contact}/custom-fieldsWrite the contact's custom field values (body: custom_fields). Response: data.message and data.contact with the current custom_fields. | Write the contact's custom field values (body: custom_fields). Response: data.message and data.contact with the current custom_fields. |
| PUT | /v1/conversations/{conversation}/custom-fieldsWrite the conversation's custom field values (body: custom_fields). Response: data.message and data.conversation with the current custom_fields. | Write the conversation's custom field values (body: custom_fields). Response: data.message and data.conversation with the current custom_fields. |
Examples
Create a select field
Request
curl -X POST "https://api.aisar.app/v1/custom-fields" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "contact",
"type": "select",
"label": "Источник",
"options": [{ "label": "Сайт" }, { "label": "Реклама" }, { "label": "Рекомендация" }],
"is_ai_readable": false
}'Response
{
"data": {
"custom_field": {
"id": 12,
"entity_type": "contact",
"key": "istochnik",
"label": "Источник",
"description": null,
"type": "select",
"options": [
{ "key": "sait", "label": "Сайт", "position": 0, "archived": false },
{ "key": "reklama", "label": "Реклама", "position": 1, "archived": false },
{ "key": "rekomendatsiia", "label": "Рекомендация", "position": 2, "archived": false }
],
"settings": {},
"is_ai_readable": false,
"position": 3,
"archived_at": null,
"created_at": "2026-11-12T09:30:00.000000Z",
"updated_at": "2026-11-12T09:30:00.000000Z"
}
}
}Write a contact's values
Request
curl -X PUT "https://api.aisar.app/v1/contacts/45/custom-fields" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"custom_fields": {
"istochnik": "reklama",
"order_number": "A-1042",
"next_call": "2026-11-20",
"old_comment": null
}
}'Response
{
"data": {
"message": "Custom fields updated.",
"contact": {
"id": 45,
"display_name": "John Doe",
"custom_fields": {
"istochnik": "reklama",
"order_number": "A-1042",
"next_call": "2026-11-20"
},
"custom_fields_meta": {
"istochnik": {
"updated_at": "2026-11-12T09:35:10+00:00",
"source": "api",
"updated_by": { "id": 7, "name": "Anna Smith" }
}
}
}
}
}A value error
Request
curl -X PUT "https://api.aisar.app/v1/conversations/8123/custom-fields" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "custom_fields": { "deadline": "20.11.2026", "ghost": "x" } }'Response
{
"data": {
"message": "The given data was invalid.",
"errors": {
"custom_fields.deadline": ["invalid_format"],
"custom_fields.ghost": ["unknown_field"]
}
}
}Archiving a field that is in use
Request
curl -X POST "https://api.aisar.app/v1/custom-fields/12/archive" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Response
{
"data": {
"message": "custom_field_in_use",
"usages": {
"automations": [{ "id": "a1b2c3", "name": "Welcome", "version_id": "v9" }],
"segments": [{ "id": 4, "name": "From ads" }],
"ai_agents": [],
"voice_agents": [],
"broadcasts": []
}
}
}The contact field catalog
Request
curl "https://api.aisar.app/v1/custom-fields?entity_type=contact" \
-H "Authorization: Bearer YOUR_API_TOKEN"Response
{
"data": {
"items": [
{
"id": 11,
"entity_type": "contact",
"key": "order_number",
"label": "Номер заказа",
"description": null,
"type": "text",
"options": null,
"settings": {},
"is_ai_readable": true,
"position": 0,
"archived_at": null,
"created_at": "2026-11-10T08:00:00.000000Z",
"updated_at": "2026-11-10T08:00:00.000000Z"
},
{
"id": 12,
"entity_type": "contact",
"key": "istochnik",
"label": "Источник",
"description": null,
"type": "select",
"options": [
{ "key": "sait", "label": "Сайт", "position": 0, "archived": false },
{ "key": "reklama", "label": "Реклама", "position": 1, "archived": false }
],
"settings": {},
"is_ai_readable": false,
"position": 1,
"archived_at": null,
"created_at": "2026-11-12T09:30:00.000000Z",
"updated_at": "2026-11-12T09:30:00.000000Z"
}
]
}
}Edit a field label and description
Request
curl -X PATCH "https://api.aisar.app/v1/custom-fields/11" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"label": "Номер заказа в магазине",
"description": "Формат A-0000",
"is_ai_readable": true
}'Response
{
"data": {
"custom_field": {
"id": 11,
"entity_type": "contact",
"key": "order_number",
"label": "Номер заказа в магазине",
"description": "Формат A-0000",
"type": "text",
"options": null,
"settings": {},
"is_ai_readable": true,
"position": 0,
"archived_at": null,
"created_at": "2026-11-10T08:00:00.000000Z",
"updated_at": "2026-11-12T10:05:00.000000Z"
}
}
}Set a new field order
Request
curl -X PUT "https://api.aisar.app/v1/custom-fields/order" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "contact",
"ids": [12, 11]
}'Response
{
"data": {
"items": [
{
"id": 12,
"entity_type": "contact",
"key": "istochnik",
"label": "Источник",
"description": null,
"type": "select",
"options": [
{ "key": "sait", "label": "Сайт", "position": 0, "archived": false },
{ "key": "reklama", "label": "Реклама", "position": 1, "archived": false }
],
"settings": {},
"is_ai_readable": false,
"position": 0,
"archived_at": null,
"created_at": "2026-11-12T09:30:00.000000Z",
"updated_at": "2026-11-12T10:10:00.000000Z"
},
{
"id": 11,
"entity_type": "contact",
"key": "order_number",
"label": "Номер заказа в магазине",
"description": "Формат A-0000",
"type": "text",
"options": null,
"settings": {},
"is_ai_readable": true,
"position": 1,
"archived_at": null,
"created_at": "2026-11-10T08:00:00.000000Z",
"updated_at": "2026-11-12T10:10:00.000000Z"
}
]
}
}Restore a field from the archive
Request
curl -X POST "https://api.aisar.app/v1/custom-fields/14/restore" \
-H "Authorization: Bearer YOUR_API_TOKEN"Response
{
"data": {
"custom_field": {
"id": 14,
"entity_type": "conversation",
"key": "deadline",
"label": "Срок",
"description": null,
"type": "date",
"options": null,
"settings": {},
"is_ai_readable": false,
"position": 2,
"archived_at": null,
"created_at": "2026-11-01T07:00:00.000000Z",
"updated_at": "2026-11-12T10:20:00.000000Z"
}
}
}Where a field is used
Request
curl "https://api.aisar.app/v1/custom-fields/12/usages" \
-H "Authorization: Bearer YOUR_API_TOKEN"Response
{
"data": {
"usages": {
"automations": [{ "id": "a1b2c3", "name": "Welcome", "version_id": "v9" }],
"segments": [{ "id": 4, "name": "From ads" }],
"ai_agents": [],
"voice_agents": [],
"broadcasts": [{ "id": 31, "name": "November promo", "status": "scheduled" }]
}
}
}Delete an archived field
Request
curl -X DELETE "https://api.aisar.app/v1/custom-fields/14" \
-H "Authorization: Bearer YOUR_API_TOKEN"Response
// 202 удаление поставлено в очередь / deletion queued
{
"data": {
"message": "custom_field_delete_queued"
}
}
// 409 поле не в архиве / the field is not archived
{
"data": {
"message": "custom_field_not_archived"
}
}