Организации
Организация — карточка компании-клиента в CRM: название, юридическое название, БИН/ИИН или ИНН, страна, тип отношений, реквизиты (организационно-правовая форма, коды, руководитель), банковские счета, телефон, e-mail, сайт, адрес, ответственный и свои поля. К организации привязываются контакты и сделки (у контакта и у сделки не больше одной организации). API покрывает список с поиском и фильтрами, подбор по названию или БИН, карточку, создание, правку, удаление, свои поля, привязку контактов, список сделок организации, справочник типов отношений и банковские счета.
Доступность и права
Организации есть только у компаний типа «бизнес»: в Kids любой эндпоинт группы отвечает 403. Токены встроенных виджетов (embed) тоже получают 403. Права проверяются раньше поиска записи, поэтому без права ответ 403 для любого id, а 404 возможен только у того, кому право выдано.
| Действие | Нужные права |
|---|---|
| Список, подбор, карточка | organization.view |
| Создание | organization.view + organization.create |
| Правка | organization.view + organization.update |
| Удаление | organization.view + organization.delete |
| Свои поля организации | organization.view + organization.update + custom_field_value.update |
| Контакты организации: список | organization.view + contact.view |
| Привязка и отвязка контактов | organization.view + contact.update |
| Сделки организации | organization.view + deal.view, тариф с функцией сделок |
| Справочник типов отношений: чтение; подсказки организационно-правовой формы | organization.view |
| Справочник типов отношений: создание, правка, архив, удаление, порядок | organization.view + organization_relation_type.manage |
| Банковские счета в карточке | organization.view + organization_bank_account.view |
| Банковские счета: добавление, правка, удаление | organization.view + organization.update + organization_bank_account.view |
По умолчанию у администратора все четыре права organization.*, у менеджера view, create и update, у оператора только view; удаление доступно только администратору. Своим ролям, у которых было право contact.view, при выкладке выдано organization.view.
organization_relation_type.manage и organization_bank_account.view по умолчанию есть у администратора и менеджера. Оператор номеров счетов не видит никогда: карточка у него приходит без ключа bank_accounts. Своим ролям эти права автоматически не выдавались: администратор отмечает их в редакторе ролей (две отдельные ячейки раздела организаций). Запись счёта требует права на просмотр счетов, потому что в ответе приходит полный номер.
Поля организации
| Поле | Описание |
|---|---|
name | Название, обязательно, до 255 символов. Не уникально. |
legal_name | Юридическое название, до 255 символов. |
tax_id | Налоговый номер (БИН/ИИН, ИНН и т. п.), до 64 символов на входе. Пробелы, дефисы и точки убираются, буквы переводятся в верхний регистр; после этого 3–32 латинские буквы и цифры. Уникален среди неудалённых организаций компании. |
country_code | Код страны ISO из двух букв, хранится в верхнем регистре. Если при создании не передан, берётся страна компании. |
relation_type_id | Тип отношений (id из справочника компании) или null. Чужой, неизвестный или неверный id: 422 relation_type_not_found; архивный тип: 422 relation_type_archived, кроме случая, когда организация уже стоит на этом же типе. В ответе рядом приходит relation_type ({id, name, color, system_key, is_archived} или null). |
legal_form | Организационно-правовая форма (ТОО, ИП, ОсОО, LLC и т. п.), свободная строка до 50 символов, без справочника и без привязки к стране. Подсказки: GET /organizations/legal-forms. |
registration_code | Регистрационный код (ОКПО и т. п.), до 32 символов, формат не проверяется. Только в карточке. |
extra_codes | Прочие коды одной строкой (КБе, КПП, код налогового органа), до 255 символов. Только в карточке. |
signatory_name | ФИО руководителя или подписанта, до 255 символов. Персональные данные. Только в карточке. |
signatory_position | Должность подписанта, до 255 символов. Только в карточке. |
signatory_basis | На каком основании действует подписант («Устава», «Доверенности № … от …»), до 255 символов. Только в карточке. |
bank_accounts | Только чтение, только в карточке и только при праве organization_bank_account.view: массив счетов (см. «Банковские счета»), счёт по умолчанию первым. Пишется отдельными эндпоинтами, не через POST/PATCH организации. |
phone | Телефон, до 40 символов на входе, хранится в формате E.164 (национальный номер читается по country_code). Нечитаемый номер: 422, код phone_invalid. |
email | E-mail до 254 символов, хранится в нижнем регистре. |
website | Адрес http:// или https://, до 255 символов. |
address | Адрес, до 500 символов. |
comments | Комментарий, до 5000 символов. В списке обрезается до 300 символов. |
responsible_user_id | Ответственный, участник текущей компании, иначе 422. В ответе рядом приходит responsible_user ({id, name} или null). |
source | Только чтение: manual (кабинет), api (API-токен интегратора), backfill (перенос из текстового поля «Компания» контактов), import (создана импортом контактов из CSV, с 2026-11-17); bitrix24, amocrm зарезервированы. |
custom_fields | Значения своих полей организации ({ключ: значение}), см. группу «Свои поля» с entity_type=organization. |
Пустая строка в любом текстовом поле сохраняется как null. В PATCH передаются только меняемые поля. Счётчики приходят, только когда сервер их посчитал: contacts_count (привязанные контакты без объединённых) в списке и карточке; open_deals_count в списке и карточке и open_deals_amount (массив {currency, amount}, сумма открытых сделок по валютам, amount строкой) в карточке. Счётчики сделок есть только у пользователя с правом deal.view на тарифе со сделками и учитывают лишь сделки, которые ему видны, без лидов из «Неразобранного». Отсутствие ключа означает «не запрашивалось», а не ноль.
В строке списка из новых полей приходят только relation_type_id, relation_type и legal_form; registration_code, extra_codes, signatory_* и bank_accounts есть лишь в карточке (GET, а также ответы POST и PATCH). Ответ PUT /organizations/{id}/custom-fields содержит реквизиты, но без bank_accounts. Отсутствие ключа bank_accounts в карточке означает, что у пользователя нет права на счета, а не что счетов нет.
Проверка БИН/ИНН
- Формат один для всех стран и от
country_codeне зависит: после удаления пробелов, точек и дефисов и перевода букв в верхний регистр остаётся от 3 до 32 латинских букв и цифр. Иначе422,tax_id_invalid_format. Контрольная цифра БИН и длина номера для конкретной страны не проверяются: у казахстанской компании можно сохранить, например, российский ИНН. - Номер проверяется при каждой передаче
tax_id; сменаcountry_codeего не перепроверяет. Если тот же номер (после такой же нормализации) уже есть у другой неудалённой организации компании:409с кодомorganization_tax_id_takenиexisting_organization_id. У удалённой организации номер освобождается.
Список и подбор
GET /organizations постраничный: page, perPage от 1 до 100 (по умолчанию 25), ответ data.items + data.pagination (page, perPage, total, lastPage). Фильтры комбинируются по И: search (до 100 символов; вхождение без учёта регистра в name, legal_name, email, phone либо начало tax_id после нормализации), responsible_user_id (id или none — без ответственного), has_tax_id (true/false), relation_type_id (id типа отношений из справочника компании или none — без типа; чужой или неизвестный id: 422 relation_type_not_found), country (код из двух букв, регистр не важен), cf[N][key|op|value] — до 5 фильтров по своим полям организации в том же формате, что у контактов. Сортировка: sortBy — name, created_at (по умолчанию), updated_at, contacts_count, relation_type (по порядку типа в справочнике; организации без типа в конце при любом направлении) или cf:<key>; sortDir — asc/desc (по умолчанию desc). Неизвестный ключ своего поля: 422, unknown_field.
GET /organizations/lookup?q= — подбор для карточки контакта или сделки: до 20 записей {id, name, tax_id} в data.items, без пагинации. Сначала точное совпадение БИН/ИНН, затем названия, начинающиеся с q, затем остальные совпадения, внутри групп по названию. Без q отдаются первые 20 организаций по названию.
GET /organizations/legal-forms — подсказки для поля legal_form: до 20 самых частых значений среди неудалённых организаций компании, по убыванию частоты, в data.items массивом строк (только значения, без id организаций).
Справочник типов отношений
У каждой компании свой справочник «Тип отношений» (/organization-relation-types). Новая компания получает шесть стартовых типов с постоянным system_key: customer (Клиент), prospect (Потенциальный клиент), partner (Партнёр), supplier (Поставщик), competitor (Конкурент), other (Другое). Их можно переименовать, перекрасить и архивировать, но не удалить (422 relation_type_system); system_key не меняется и в запросах не принимается (422), поэтому по нему удобно писать условия в интеграции. У своих типов system_key равен null.
- Тип:
id,name(до 100 символов, уникально без учёта регистра среди неархивных, иначе422relation_type_name_taken),color(green,blue,violet,amber,red,gray),system_key,position,is_archived,organizations_count(неудалённые организации этого типа; приходит в ответах списка и смены порядка),created_at,updated_at. GET— типы по порядку вdata.items, без архивных;include_archived=trueдобавляет архивные.POSTсnameиcolor—201, вdataсозданный тип. Неархивных типов не больше 50:422relation_types_limit.PATCH /organization-relation-types/{id}—name,color,is_archived(архив и возврат из архива). Архивный тип нельзя назначить новой организации, но у тех, кто уже на нём стоит, он остаётся.DELETE—204. Тип, который стоит хотя бы у одной организации (включая удалённые), не удаляется:409с кодомrelation_type_in_useиorganizations_count; такой тип архивируют.PUT /organization-relation-types/orderсids— все id справочника компании, включая архивные, каждый по одному разу, в новом порядке. Неполный, лишний или чужой набор:422relation_type_order_mismatchна полеids. Ответ: весь справочник с архивными вdata.items.- Тип другой компании или id в неверном формате:
404{"data": {"message": "Relation type not found."}}. Правка справочника событий вебхуков не отправляет; смена типа у организации приходит вorganization.updatedсchanged_fields: ["relation_type_id"].
Банковские счета
Счета организации пишутся через /organizations/{id}/bank-accounts, а читаются в карточке (bank_accounts); отдельного эндпоинта списка счетов нет. Счёт: id, bank_name (до 255 символов), bank_bik (БИК или SWIFT банка), bank_account (полный номер счёта или IBAN), currency (KZT, KGS, RUB, USD, EUR; если не передана, берётся валюта сделок компании), is_default, position (0–1000; по умолчанию в конец), created_at, updated_at. Номер хранится зашифрованным и в журнал аудита попадают только последние четыре символа.
- В
bank_accountиbank_bikубираются пробелы, точки и дефисы, буквы переводятся в верхний регистр. После этого номер — 8–34 латинские буквы и цифры (иначе422bank_account_invalid_format), код банка — 6–11 (иначе422bank_bik_invalid_format). Значения в тексте ошибок не возвращаются. POST(bank_accountобязателен) —201, вdataсозданный счёт;PATCH .../bank-accounts/{account}— только переданные поля, вdataсчёт;DELETE—204. Не больше 20 счетов у организации:422bank_accounts_limit.- Счёт по умолчанию у организации один. Первый счёт становится им сам;
is_default: trueснимает флаг с прежнего;is_default: falseу единственного счёта ничего не меняет, а у одного из нескольких передаёт флаг самому раннему из оставшихся (поposition, затемid); при удалении счёта по умолчанию флаг тоже переходит к самому раннему. Если два запроса одновременно меняют счёт по умолчанию, проигравший получает409bank_account_default_conflict; запрос можно повторить. - Организация не найдена:
404Organization not found.; счёт другой организации, другой компании или id в неверном формате:404Bank account not found.. - Каждое изменение счёта отправляет
organization.updatedсchanged_fields: ["bank_accounts"]. Сами счета в тело вебхука не входят: интегратор с правом на счета дозапрашивает карточку.
Удаление
Удаление мягкое. Привязки контактов и сделок сохраняются, но пока организация удалена, у этих контактов и сделок organization и organization_id равны null, а сама организация отвечает 404. Эндпоинта восстановления в API нет. Ответ: {"data": {"message": "Organization deleted."}}.
Контакты и сделки организации
GET /organizations/{id}/contacts — привязанные контакты (page, perPage от 1 до 100, по умолчанию 20; порядок по имени), элементы в формате ресурса контакта. POST /organizations/{id}/contacts с contact_ids (от 1 до 100 разных id неудалённых и необъединённых контактов компании, иначе 422 на contact_ids.N) привязывает контакты пачкой; контакт другой организации переносится. Ответ {"data": {"message": "Contacts linked.", "linked_contact_ids": [...]}} перечисляет только контакты, у которых организация действительно поменялась. По каждому из них уходит contact.updated с data.changed_fields: ["organization_id"]; привязка пачкой не запускает сценарии и не синхронизирует контакты с Bitrix24/amoCRM. DELETE /organizations/{id}/contacts/{contact} отвязывает один контакт как обычную правку контакта; контакт не из этой организации или недоступный пользователю: 404.
GET /organizations/{id}/deals — сделки организации, видимые пользователю по его уровню доступа, без лидов из «Неразобранного»: status (open, won, lost), page, perPage от 1 до 100 (по умолчанию 20), порядок по updated_at по убыванию, элементы в формате ресурса сделки.
Свои поля организации пишутся через PUT /organizations/{id}/custom-fields с телом custom_fields в том же формате, что у контакта. Ответ: {"data": {"message": "Custom fields updated.", "organization": {...}}}. Изменение уходит событием organization.updated с changed_fields вида custom.<key>.
Экспорт, импорт, сценарии и MCP
С 2026-11-17: выгрузка организаций — POST /exports с type=organizations (фильтры как у GET /organizations, банковских счетов в файле нет; см. группу «Экспорт»). В импорте контактов из CSV колонки organization и organization_tax_id находят или создают организацию и привязывают к ней контакт (см. «Импорт контактов из CSV» в группе «Контакты»). В сценариях есть блок crm-find-organization и сущность organization в блоке «Получить значение поля». Через MCP организации создаются, правятся и привязываются к контактам инструментами create_organization, update_organization и link_contact_to_organization (см. руководство по MCP); банковские счета MCP не читает и не пишет.
Ошибки и лимиты
403— нет права, компания не типа «бизнес» или embed-токен.404{"data": {"message": "Organization not found."}}— организация другой компании, удалённая или id в неверном формате.409organization_tax_id_taken— БИН/ИНН занят другой организацией компании, в ответеexisting_organization_id.409relation_type_in_use— удаляемый тип отношений стоит у организаций, в ответеorganizations_count;409bank_account_default_conflict— одновременная смена счёта по умолчанию.422— ошибки валидации в формате{"data": {"message", "errors": {поле: [код]}}}:tax_id_invalid_format,phone_invalid, ответственный не из компании, неверныеcontact_ids,relation_type_not_found,relation_type_archived,relation_type_name_taken,relation_types_limit,relation_type_order_mismatch,relation_type_system,bank_account_invalid_format,bank_bik_invalid_format,bank_accounts_limit.429— список, подбор, подсказки формы, справочник типов (чтение), контакты и сделки организации: 120 запросов в минуту на пользователя; создание, правка, удаление, привязка и отвязка, запись справочника типов и счетов: 60 в минуту; карточка: общий лимит тяжёлых запросов API-токена (120 в минуту); свои поля: лимит записи значений своих полей.
Эндпоинты
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/organizationsСписок организаций компании (query: page, perPage 1–100, search, responsible_user_id = id|none, has_tax_id, relation_type_id = id|none, country, sortBy = name|created_at|updated_at|contacts_count|relation_type|cf:<key>, sortDir, cf[N][key|op|value]). Ответ: data.items + data.pagination. | Список организаций компании (query: page, perPage 1–100, search, responsible_user_id = id|none, has_tax_id, relation_type_id = id|none, country, sortBy = name|created_at|updated_at|contacts_count|relation_type|cf:<key>, sortDir, cf[N][key|op|value]). Ответ: data.items + data.pagination. |
| GET | /v1/organizations/lookupПодбор организации по названию или БИН/ИНН (query: q до 100 символов). Ответ: data.items — до 20 записей {id, name, tax_id}. | Подбор организации по названию или БИН/ИНН (query: q до 100 символов). Ответ: data.items — до 20 записей {id, name, tax_id}. |
| GET | /v1/organizations/legal-formsПодсказки организационно-правовой формы: до 20 самых частых значений legal_form в компании. Ответ: data.items — массив строк. | Подсказки организационно-правовой формы: до 20 самых частых значений legal_form в компании. Ответ: data.items — массив строк. |
| POST | /v1/organizationsСоздать организацию (body: name, legal_name?, tax_id?, country_code?, relation_type_id?, legal_form?, registration_code?, extra_codes?, signatory_name?, signatory_position?, signatory_basis?, phone?, email?, website?, address?, comments?, responsible_user_id?) — 201, data — карточка. 409 organization_tax_id_taken. | Создать организацию (body: name, legal_name?, tax_id?, country_code?, relation_type_id?, legal_form?, registration_code?, extra_codes?, signatory_name?, signatory_position?, signatory_basis?, phone?, email?, website?, address?, comments?, responsible_user_id?) — 201, data — карточка. 409 organization_tax_id_taken. |
| GET | /v1/organizations/{organization}Карточка организации: поля и реквизиты, relation_type, свои поля с custom_fields_meta, contacts_count, (при праве deal.view) open_deals_count и open_deals_amount, (при праве organization_bank_account.view) bank_accounts. | Карточка организации: поля и реквизиты, relation_type, свои поля с custom_fields_meta, contacts_count, (при праве deal.view) open_deals_count и open_deals_amount, (при праве organization_bank_account.view) bank_accounts. |
| PATCH | /v1/organizations/{organization}Изменить поля организации (только переданные). Ответ — карточка. 409 organization_tax_id_taken. | Изменить поля организации (только переданные). Ответ — карточка. 409 organization_tax_id_taken. |
| DELETE | /v1/organizations/{organization}Удалить организацию (мягко; привязки сохраняются, но читаются как null). | Удалить организацию (мягко; привязки сохраняются, но читаются как null). |
| PUT | /v1/organizations/{organization}/custom-fieldsЗаписать значения своих полей организации (body: custom_fields). Ответ: data.message и data.organization. | Записать значения своих полей организации (body: custom_fields). Ответ: data.message и data.organization. |
| GET | /v1/organizations/{organization}/contactsКонтакты организации (query: page, perPage 1–100). Ответ: data.items + data.pagination. Нужно ещё право contact.view. | Контакты организации (query: page, perPage 1–100). Ответ: data.items + data.pagination. Нужно ещё право contact.view. |
| POST | /v1/organizations/{organization}/contactsПривязать контакты пачкой (body: contact_ids — 1–100 id). Ответ: data.linked_contact_ids. Нужно ещё право contact.update. | Привязать контакты пачкой (body: contact_ids — 1–100 id). Ответ: data.linked_contact_ids. Нужно ещё право contact.update. |
| DELETE | /v1/organizations/{organization}/contacts/{contact}Отвязать один контакт от организации. Нужно ещё право contact.update. | Отвязать один контакт от организации. Нужно ещё право contact.update. |
| GET | /v1/organizations/{organization}/dealsСделки организации, видимые пользователю (query: status = open|won|lost, page, perPage 1–100). Ответ: data.items + data.pagination. Нужны право deal.view и тариф со сделками. | Сделки организации, видимые пользователю (query: status = open|won|lost, page, perPage 1–100). Ответ: data.items + data.pagination. Нужны право deal.view и тариф со сделками. |
| POST | /v1/organizations/{organization}/bank-accountsДобавить банковский счёт (body: bank_account, bank_name?, bank_bik?, currency?, is_default?, position?) — 201, data — счёт. Нужны ещё organization.update и organization_bank_account.view. | Добавить банковский счёт (body: bank_account, bank_name?, bank_bik?, currency?, is_default?, position?) — 201, data — счёт. Нужны ещё organization.update и organization_bank_account.view. |
| PATCH | /v1/organizations/{organization}/bank-accounts/{account}Изменить банковский счёт (только переданные поля). Ответ: data — счёт. 409 bank_account_default_conflict. Нужны ещё organization.update и organization_bank_account.view. | Изменить банковский счёт (только переданные поля). Ответ: data — счёт. 409 bank_account_default_conflict. Нужны ещё organization.update и organization_bank_account.view. |
| DELETE | /v1/organizations/{organization}/bank-accounts/{account}Удалить банковский счёт — 204; флаг «по умолчанию» переходит к самому раннему из оставшихся. Нужны ещё organization.update и organization_bank_account.view. | Удалить банковский счёт — 204; флаг «по умолчанию» переходит к самому раннему из оставшихся. Нужны ещё organization.update и organization_bank_account.view. |
| GET | /v1/organization-relation-typesСправочник типов отношений по порядку (query: include_archived). Ответ: data.items с organizations_count. | Справочник типов отношений по порядку (query: include_archived). Ответ: data.items с organizations_count. |
| POST | /v1/organization-relation-typesСоздать тип отношений (body: name, color) — 201, data — тип. 422 relation_type_name_taken, relation_types_limit. | Создать тип отношений (body: name, color) — 201, data — тип. 422 relation_type_name_taken, relation_types_limit. |
| PUT | /v1/organization-relation-types/orderНовый порядок справочника (body: ids — все id компании, включая архивные). Ответ: data.items. 422 relation_type_order_mismatch. | Новый порядок справочника (body: ids — все id компании, включая архивные). Ответ: data.items. 422 relation_type_order_mismatch. |
| PATCH | /v1/organization-relation-types/{relationType}Переименовать, перекрасить, архивировать или вернуть из архива (body: name?, color?, is_archived?). Ответ: data — тип. | Переименовать, перекрасить, архивировать или вернуть из архива (body: name?, color?, is_archived?). Ответ: data — тип. |
| DELETE | /v1/organization-relation-types/{relationType}Удалить тип отношений — 204. 409 relation_type_in_use (с organizations_count), 422 relation_type_system для стартового типа. | Удалить тип отношений — 204. 409 relation_type_in_use (с organizations_count), 422 relation_type_system для стартового типа. |
Примеры
Создание организации
Запрос
curl -X POST "https://api.aisar.app/v1/organizations" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Альфа Трейд",
"legal_name": "ТОО «Альфа Трейд»",
"tax_id": "1203 4056 7891",
"country_code": "KZ",
"relation_type_id": 31,
"legal_form": "ТОО",
"signatory_name": "Иван Петров",
"signatory_position": "Директор",
"signatory_basis": "Устава",
"email": "Office@Example.com",
"website": "https://example.com",
"responsible_user_id": 7
}'Ответ
{
"data": {
"id": 12,
"name": "Альфа Трейд",
"legal_name": "ТОО «Альфа Трейд»",
"tax_id": "120340567891",
"country_code": "KZ",
"relation_type_id": 31,
"relation_type": { "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "is_archived": false },
"legal_form": "ТОО",
"registration_code": null,
"extra_codes": null,
"signatory_name": "Иван Петров",
"signatory_position": "Директор",
"signatory_basis": "Устава",
"phone": null,
"email": "office@example.com",
"website": "https://example.com",
"address": null,
"comments": null,
"responsible_user_id": 7,
"responsible_user": { "id": 7, "name": "Anna Smith" },
"source": "api",
"contacts_count": 0,
"open_deals_count": 0,
"open_deals_amount": [],
"bank_accounts": [],
"custom_fields": {},
"custom_fields_meta": {},
"created_at": "2026-11-17T09:30:00.000000Z",
"updated_at": "2026-11-17T09:30:00.000000Z"
}
}БИН/ИНН уже занят
Запрос
curl -X POST "https://api.aisar.app/v1/organizations" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Альфа", "tax_id": "120340567891", "country_code": "KZ" }'Ответ
{
"data": {
"message": "An organization with this tax id already exists.",
"code": "organization_tax_id_taken",
"existing_organization_id": 12
}
}Список с фильтром и сортировкой
Запрос
curl "https://api.aisar.app/v1/organizations?search=%D0%B0%D0%BB%D1%8C%D1%84%D0%B0&has_tax_id=true&sortBy=name&sortDir=asc&perPage=25" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"data": {
"items": [
{
"id": 12,
"name": "Альфа Трейд",
"legal_name": "ТОО «Альфа Трейд»",
"tax_id": "120340567891",
"country_code": "KZ",
"relation_type_id": 31,
"relation_type": { "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "is_archived": false },
"legal_form": "ТОО",
"phone": "+12025550142",
"email": "office@example.com",
"website": "https://example.com",
"address": null,
"comments": "Оптовый клиент, договор до конца года",
"responsible_user_id": 7,
"responsible_user": { "id": 7, "name": "Anna Smith" },
"source": "manual",
"contacts_count": 3,
"open_deals_count": 2,
"custom_fields": { "segment": "wholesale" },
"created_at": "2026-11-17T09:30:00.000000Z",
"updated_at": "2026-11-17T10:05:00.000000Z"
}
],
"pagination": { "page": 1, "perPage": 25, "total": 1, "lastPage": 1 }
}
}Привязка контактов
Запрос
curl -X POST "https://api.aisar.app/v1/organizations/12/contacts" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "contact_ids": [45, 46, 47] }'Ответ
{
"data": {
"message": "Contacts linked.",
"linked_contact_ids": [45, 47]
}
}Банковский счёт
Запрос
curl -X POST "https://api.aisar.app/v1/organizations/12/bank-accounts" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"bank_name": "Example Bank",
"bank_bik": "EXMPKZKA",
"bank_account": "KZ00 0000 0000 0000 0001",
"currency": "KZT"
}'Ответ
{
"data": {
"id": 5,
"bank_name": "Example Bank",
"bank_bik": "EXMPKZKA",
"bank_account": "KZ000000000000000001",
"currency": "KZT",
"is_default": true,
"position": 1,
"created_at": "2026-11-17T09:40:00.000000Z",
"updated_at": "2026-11-17T09:40:00.000000Z"
}
}Свой тип отношений
Запрос
curl -X POST "https://api.aisar.app/v1/organization-relation-types" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Дистрибьютор", "color": "blue" }'Ответ
{
"data": {
"id": 37,
"name": "Дистрибьютор",
"color": "blue",
"system_key": null,
"position": 7,
"is_archived": false,
"created_at": "2026-11-17T09:45:00.000000Z",
"updated_at": "2026-11-17T09:45:00.000000Z"
}
}Тип отношений используется
Запрос
curl -X DELETE "https://api.aisar.app/v1/organization-relation-types/37" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"data": {
"message": "The relation type is used by organizations; archive it instead.",
"code": "relation_type_in_use",
"organizations_count": 4
}
}Подбор по названию или БИН/ИНН
Запрос
curl "https://api.aisar.app/v1/organizations/lookup?q=120340567891" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"items": [
{ "id": 12, "name": "Альфа Трейд", "tax_id": "120340567891" }
]
}
}Подсказки организационно-правовой формы
Запрос
curl "https://api.aisar.app/v1/organizations/legal-forms" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"items": ["ТОО", "ИП", "АО"]
}
}Карточка организации
Запрос
curl "https://api.aisar.app/v1/organizations/12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"id": 12,
"name": "Альфа Трейд",
"legal_name": "ТОО «Альфа Трейд»",
"tax_id": "120340567891",
"country_code": "KZ",
"relation_type_id": 31,
"relation_type": { "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "is_archived": false },
"legal_form": "ТОО",
"registration_code": null,
"extra_codes": null,
"signatory_name": "Иван Петров",
"signatory_position": "Директор",
"signatory_basis": "Устава",
"phone": "+12025550142",
"email": "office@example.com",
"website": "https://example.com",
"address": null,
"comments": "Оптовый клиент, договор до конца года",
"responsible_user_id": 7,
"responsible_user": { "id": 7, "name": "Anna Smith" },
"source": "manual",
"contacts_count": 3,
"open_deals_count": 2,
"open_deals_amount": [
{ "currency": "KZT", "amount": "1500000.00" }
],
"bank_accounts": [
{
"id": 5,
"bank_name": "Example Bank",
"bank_bik": "EXMPKZKA",
"bank_account": "KZ000000000000000001",
"currency": "KZT",
"is_default": true,
"position": 1,
"created_at": "2026-11-17T09:40:00.000000Z",
"updated_at": "2026-11-17T09:40:00.000000Z"
}
],
"custom_fields": { "segment": "wholesale" },
"custom_fields_meta": {
"segment": { "updated_at": "2026-11-17T10:05:00.000000Z", "source": "manual", "updated_by": { "id": 7, "name": "Anna Smith" } }
},
"created_at": "2026-11-17T09:30:00.000000Z",
"updated_at": "2026-11-17T10:05:00.000000Z"
}
}Изменить организацию
Запрос
curl -X PATCH "https://api.aisar.app/v1/organizations/12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "phone": "+12025550143", "address": "Example street 1" }'Ответ
{
"data": {
"id": 12,
"name": "Альфа Трейд",
"phone": "+12025550143",
"address": "Example street 1",
"...": "...",
"updated_at": "2026-11-17T11:00:00.000000Z"
}
}Удалить организацию
Запрос
curl -X DELETE "https://api.aisar.app/v1/organizations/12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"message": "Organization deleted."
}
}Записать свои поля организации
Запрос
curl -X PUT "https://api.aisar.app/v1/organizations/12/custom-fields" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "custom_fields": { "segment": "retail" } }'Ответ
{
"data": {
"message": "Custom fields updated.",
"organization": {
"id": 12,
"name": "Альфа Трейд",
"...": "...",
"custom_fields": { "segment": "retail" },
"custom_fields_meta": {
"segment": { "updated_at": "2026-11-17T11:10:00.000000Z", "source": "api", "updated_by": { "id": 7, "name": "Anna Smith" } }
}
}
}
}Контакты организации
Запрос
curl "https://api.aisar.app/v1/organizations/12/contacts?page=1&perPage=20" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"items": [
{
"id": 45,
"displayName": "Ivan Petrov",
"firstName": "Ivan",
"lastName": "Petrov",
"organization_id": 12,
"organization": { "id": 12, "name": "Альфа Трейд" },
"phones": [{ "phone": "+12025550143", "type": "mobile" }],
"...": "..."
}
],
"pagination": { "page": 1, "perPage": 20, "total": 3, "lastPage": 1 }
}
}Отвязать контакт
Запрос
curl -X DELETE "https://api.aisar.app/v1/organizations/12/contacts/45" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"message": "Contact unlinked."
}
}Открытые сделки организации
Запрос
curl "https://api.aisar.app/v1/organizations/12/deals?status=open&perPage=20" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"items": [
{
"id": 301,
"contact_id": 45,
"organization_id": 12,
"organization": { "id": 12, "name": "Альфа Трейд" },
"funnel_id": 3,
"funnel_stage_id": 11,
"title": "Поставка оборудования",
"amount": "1500000.00",
"currency": "KZT",
"status": "open",
"contact": { "id": 45, "display_name": "Ivan Petrov", "avatar": null },
"responsible_user": { "id": 7, "name": "Anna Smith" },
"...": "..."
}
],
"pagination": { "page": 1, "perPage": 20, "total": 2, "lastPage": 1 }
}
}Изменить банковский счёт
Запрос
curl -X PATCH "https://api.aisar.app/v1/organizations/12/bank-accounts/5" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "bank_name": "Example Bank Central", "currency": "USD" }'Ответ
{
"data": {
"id": 5,
"bank_name": "Example Bank Central",
"bank_bik": "EXMPKZKA",
"bank_account": "KZ000000000000000001",
"currency": "USD",
"is_default": true,
"position": 1,
"created_at": "2026-11-17T09:40:00.000000Z",
"updated_at": "2026-11-17T11:20:00.000000Z"
}
}Удалить банковский счёт (204)
Запрос
curl -X DELETE "https://api.aisar.app/v1/organizations/12/bank-accounts/5" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Справочник типов отношений
Запрос
curl "https://api.aisar.app/v1/organization-relation-types?include_archived=true" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"items": [
{ "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "position": 1, "is_archived": false, "organizations_count": 18, "created_at": "2026-11-17T09:00:00.000000Z", "updated_at": "2026-11-17T09:00:00.000000Z" },
{ "id": 32, "name": "Потенциальный клиент", "color": "blue", "system_key": "prospect", "position": 2, "is_archived": false, "organizations_count": 6, "created_at": "2026-11-17T09:00:00.000000Z", "updated_at": "2026-11-17T09:00:00.000000Z" },
{ "id": 37, "name": "Дистрибьютор", "color": "blue", "system_key": null, "position": 7, "is_archived": true, "organizations_count": 0, "created_at": "2026-11-17T09:45:00.000000Z", "updated_at": "2026-11-17T12:00:00.000000Z" },
{ "...": "..." }
]
}
}Порядок типов отношений
Запрос
curl -X PUT "https://api.aisar.app/v1/organization-relation-types/order" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "ids": [32, 31, 33, 34, 35, 36, 37] }'Ответ
{
"data": {
"items": [
{ "id": 32, "name": "Потенциальный клиент", "color": "blue", "system_key": "prospect", "position": 1, "is_archived": false, "organizations_count": 6, "created_at": "2026-11-17T09:00:00.000000Z", "updated_at": "2026-11-17T12:10:00.000000Z" },
{ "id": 31, "name": "Клиент", "color": "green", "system_key": "customer", "position": 2, "is_archived": false, "organizations_count": 18, "created_at": "2026-11-17T09:00:00.000000Z", "updated_at": "2026-11-17T12:10:00.000000Z" },
{ "...": "..." }
]
}
}Архивировать тип отношений
Запрос
curl -X PATCH "https://api.aisar.app/v1/organization-relation-types/37" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "is_archived": true }'Ответ
{
"data": {
"id": 37,
"name": "Дистрибьютор",
"color": "blue",
"system_key": null,
"position": 7,
"is_archived": true,
"created_at": "2026-11-17T09:45:00.000000Z",
"updated_at": "2026-11-17T12:00:00.000000Z"
}
}