Organizations
An organization is the CRM record of a client company: name, legal name, tax id (BIN/IIN or INN), country, relation type, requisites (legal form, codes, signatory), bank accounts, phone, e-mail, website, address, responsible user and custom fields. Contacts and deals are linked to an organization (a contact or a deal has at most one organization). The API covers the list with search and filters, a picker by name or tax id, the card, create, edit, delete, custom fields, linking contacts, the deals of an organization, the relation type catalog and bank accounts.
Availability and permissions
Organizations exist only in companies of the "business" type: in Kids every endpoint of the group answers 403. Embed widget tokens get 403 as well. Permissions are checked before the record is looked up, so without the permission the answer is 403 for any id, and 404 is possible only for a caller who holds it.
| Action | Required permissions |
|---|---|
| List, picker, card | organization.view |
| Create | organization.view + organization.create |
| Edit | organization.view + organization.update |
| Delete | organization.view + organization.delete |
| Organization custom fields | organization.view + organization.update + custom_field_value.update |
| Organization contacts: list | organization.view + contact.view |
| Linking and unlinking contacts | organization.view + contact.update |
| Organization deals | organization.view + deal.view, a plan with the deals feature |
| Relation type catalog: read; legal form hints | organization.view |
| Relation type catalog: create, edit, archive, delete, reorder | organization.view + organization_relation_type.manage |
| Bank accounts in the card | organization.view + organization_bank_account.view |
| Bank accounts: add, edit, delete | organization.view + organization.update + organization_bank_account.view |
By default the administrator holds all four organization.* permissions, the manager view, create and update, the agent only view; deleting is administrator-only. Custom roles that held contact.view were granted organization.view at rollout.
organization_relation_type.manage and organization_bank_account.view are held by default by the administrator and the manager. The agent never sees account numbers: their card comes without the bank_accounts key. Custom roles were not granted these permissions automatically: an administrator ticks them in the role editor (two separate cells of the organizations section). Writing an account requires the account view permission, because the response carries the full number.
Organization fields
| Field | Description |
|---|---|
name | Name, required, up to 255 characters. Not unique. |
legal_name | Legal name, up to 255 characters. |
tax_id | Tax id (BIN/IIN, INN and the like), up to 64 characters on input. Spaces, dashes and dots are removed and letters upper-cased; 3-32 Latin letters and digits must remain. Unique among the live organizations of the company. |
country_code | A two-letter ISO country code, stored upper-case. When omitted on create, the company country is used. |
relation_type_id | Relation type (an id of the company catalog) or null. A foreign, unknown or malformed id is 422 relation_type_not_found; an archived type is 422 relation_type_archived, unless the organization already has that very type. The response also carries relation_type ({id, name, color, system_key, is_archived} or null). |
legal_form | Legal form (LLP, sole proprietor, LLC and the like), a free string up to 50 characters, no catalog and no country logic. Hints: GET /organizations/legal-forms. |
registration_code | Registration code (OKPO and the like), up to 32 characters, the format is not checked. Card only. |
extra_codes | Other codes as one string (beneficiary code, KPP, tax office code), up to 255 characters. Card only. |
signatory_name | Full name of the head or signatory, up to 255 characters. Personal data. Card only. |
signatory_position | Position of the signatory, up to 255 characters. Card only. |
signatory_basis | What the signatory acts on ("the Charter", "Power of attorney No. … of …"), up to 255 characters. Card only. |
bank_accounts | Read-only, card only and only with organization_bank_account.view: an array of accounts (see "Bank accounts"), the default account first. Written by separate endpoints, not through the organization POST/PATCH. |
phone | Phone, up to 40 characters on input, stored as E.164 (a national number is read using country_code). An unreadable number is 422 with the code phone_invalid. |
email | E-mail up to 254 characters, stored lower-case. |
website | An http:// or https:// address, up to 255 characters. |
address | Address, up to 500 characters. |
comments | Comment, up to 5000 characters. Cut to 300 characters in the list. |
responsible_user_id | Responsible user, a member of the current company, otherwise 422. The response also carries responsible_user ({id, name} or null). |
source | Read-only: manual (the cabinet), api (an integrator API token), backfill (moved over from the contacts "Company" text field), import (created by a CSV contact import, since 2026-11-17); bitrix24, amocrm are reserved. |
custom_fields | Values of the organization custom fields ({key: value}), see the "Custom fields" group with entity_type=organization. |
An empty string in any text field is stored as null. A PATCH carries only the fields being changed. Counters come only when the server computed them: contacts_count (linked contacts, merged ones excluded) in the list and the card; open_deals_count in the list and the card and open_deals_amount (an array of {currency, amount}, the open deals total per currency, amount as a string) in the card. Deal counters are present only for a user with deal.view on a plan with deals and count only the deals visible to that user, without leads waiting in "Unsorted". A missing key means "not requested", not zero.
Of the new fields a list row carries only relation_type_id, relation_type and legal_form; registration_code, extra_codes, signatory_* and bank_accounts are in the card only (GET, as well as the POST and PATCH responses). The PUT /organizations/{id}/custom-fields response carries the requisites but no bank_accounts. A card without the bank_accounts key means the user has no permission for accounts, not that there are no accounts.
Tax id validation
- One format for every country, independent of
country_code: after removing spaces, dots and dashes and upper-casing letters, 3 to 32 Latin letters and digits must remain. Otherwise422,tax_id_invalid_format. Neither the BIN check digit nor a country-specific length is checked: a Kazakh company can store, say, a Russian INN. - The number is checked whenever
tax_idis sent; changingcountry_codedoes not re-check it. When another live organization of the company already holds the same number (after the same normalization):409with the codeorganization_tax_id_takenandexisting_organization_id. A deleted organization frees its number.
List and picker
GET /organizations is paginated: page, perPage 1 to 100 (default 25), response data.items + data.pagination (page, perPage, total, lastPage). Filters are combined with AND: search (up to 100 characters; a case-insensitive substring of name, legal_name, email, phone, or a prefix of the normalized tax_id), responsible_user_id (an id or none for no responsible user), has_tax_id (true/false), relation_type_id (a relation type id of the company catalog or none for no type; a foreign or unknown id is 422 relation_type_not_found), country (a two-letter code, case-insensitive), cf[N][key|op|value] — up to 5 filters by organization custom fields, same format as for contacts. Sorting: sortBy — name, created_at (default), updated_at, contacts_count, relation_type (by the type position in the catalog; organizations without a type come last in either direction) or cf:<key>; sortDir — asc/desc (default desc). An unknown custom field key is 422, unknown_field.
GET /organizations/lookup?q= is the picker for a contact or deal card: up to 20 {id, name, tax_id} records in data.items, no pagination. An exact tax id match comes first, then names starting with q, then the other matches, each group ordered by name. Without q the first 20 organizations by name are returned.
GET /organizations/legal-forms returns hints for the legal_form field: up to 20 most frequent values among the live organizations of the company, by frequency descending, in data.items as an array of strings (values only, no organization ids).
Relation type catalog
Every company has its own "Relation type" catalog (/organization-relation-types). A new company gets six starter types with a permanent system_key: customer, prospect, partner, supplier, competitor, other (Russian names by default). They can be renamed, recolored and archived but not deleted (422 relation_type_system); system_key never changes and is not accepted in requests (422), so it is the stable key for conditions in an integration. Custom types have system_key set to null.
- A type:
id,name(up to 100 characters, unique case-insensitively among non-archived types, otherwise422relation_type_name_taken),color(green,blue,violet,amber,red,gray),system_key,position,is_archived,organizations_count(live organizations of this type; present in the list and reorder responses),created_at,updated_at. GETreturns the types in order indata.items, archived ones excluded;include_archived=trueadds them.POSTwithnameandcoloris201with the created type indata. At most 50 non-archived types:422relation_types_limit.PATCH /organization-relation-types/{id}takesname,color,is_archived(archive and restore). An archived type cannot be assigned to another organization, but organizations already on it keep it.DELETEis204. A type used by at least one organization (deleted ones included) is not deleted:409with the coderelation_type_in_useandorganizations_count; archive such a type instead.PUT /organization-relation-types/orderwithids: every id of the company catalog, archived ones included, each once, in the new order. An incomplete, extra or foreign set is422relation_type_order_mismatchonids. Response: the whole catalog, archived included, indata.items.- A type of another company or a malformed id is
404{"data": {"message": "Relation type not found."}}. Catalog edits send no webhook events; changing the type of an organization arrives asorganization.updatedwithchanged_fields: ["relation_type_id"].
Bank accounts
Organization accounts are written through /organizations/{id}/bank-accounts and read in the card (bank_accounts); there is no separate account list endpoint. An account: id, bank_name (up to 255 characters), bank_bik (the bank BIK or SWIFT code), bank_account (the full account number or IBAN), currency (KZT, KGS, RUB, USD, EUR; when omitted, the company deal currency is used), is_default, position (0-1000; appended by default), created_at, updated_at. The number is stored encrypted and the audit log keeps only its last four characters.
- Spaces, dots and dashes are removed from
bank_accountandbank_bikand letters upper-cased. Then the number must be 8-34 Latin letters and digits (otherwise422bank_account_invalid_format), the bank code 6-11 (otherwise422bank_bik_invalid_format). Error texts never echo the values. POST(bank_accountis required) is201with the created account indata;PATCH .../bank-accounts/{account}takes only the fields sent, the account indata;DELETEis204. At most 20 accounts per organization:422bank_accounts_limit.- An organization has one default account. The first account becomes the default by itself;
is_default: truetakes the flag from the previous one;is_default: falseon the only account changes nothing, and on one of several hands the flag to the earliest remaining account (byposition, thenid); deleting the default account also hands the flag to the earliest one. When two requests change the default account at once, the loser gets409bank_account_default_conflict; the request can be retried. - An organization that is not found is
404Organization not found.; an account of another organization or company, or a malformed id, is404Bank account not found.. - Every account change sends
organization.updatedwithchanged_fields: ["bank_accounts"]. The accounts themselves are not in the webhook body: an integrator allowed to see accounts fetches the card.
Deletion
Deletion is soft. Links of contacts and deals are kept, but while the organization is deleted those contacts and deals show organization and organization_id as null, and the organization itself answers 404. There is no restore endpoint in the API. Response: {"data": {"message": "Organization deleted."}}.
Contacts and deals of an organization
GET /organizations/{id}/contacts lists the linked contacts (page, perPage 1 to 100, default 20; ordered by name), items in the contact resource format. POST /organizations/{id}/contacts with contact_ids (1 to 100 distinct ids of live, unmerged contacts of the company, otherwise 422 on contact_ids.N) links contacts in bulk; a contact of another organization is moved. The response {"data": {"message": "Contacts linked.", "linked_contact_ids": [...]}} lists only the contacts whose organization really changed. Each of them gets a contact.updated with data.changed_fields: ["organization_id"]; bulk linking runs no scenarios and does not sync contacts to Bitrix24/amoCRM. DELETE /organizations/{id}/contacts/{contact} unlinks one contact as an ordinary contact edit; a contact outside this organization or not visible to the user is 404.
GET /organizations/{id}/deals lists the deals of the organization visible to the user at their access level, without leads waiting in "Unsorted": status (open, won, lost), page, perPage 1 to 100 (default 20), ordered by updated_at descending, items in the deal resource format.
Organization custom fields are written via PUT /organizations/{id}/custom-fields with a custom_fields body in the same format as for a contact. Response: {"data": {"message": "Custom fields updated.", "organization": {...}}}. The change is sent as an organization.updated event with changed_fields of the form custom.<key>.
Export, import, scenarios and MCP
Since 2026-11-17: organizations are exported with POST /exports and type=organizations (the filters of GET /organizations, no bank accounts in the file; see the Exports group). In the CSV contact import the organization and organization_tax_id columns find or create an organization and link the contact to it (see "CSV contact import" in the Contacts group). Scenarios get the crm-find-organization block and the organization entity in the "Get field value" block. Over MCP organizations are created, updated and linked to contacts with create_organization, update_organization and link_contact_to_organization (see the MCP guide); MCP never reads or writes bank accounts.
Errors and limits
403— missing permission, a non-business company or an embed token.404{"data": {"message": "Organization not found."}}— an organization of another company, a deleted one or a malformed id.409organization_tax_id_taken— the tax id is held by another organization of the company, the response carriesexisting_organization_id.409relation_type_in_use— the relation type being deleted is used by organizations, the response carriesorganizations_count;409bank_account_default_conflict— a concurrent change of the default account.422— validation errors shaped{"data": {"message", "errors": {field: [code]}}}:tax_id_invalid_format,phone_invalid, a responsible user outside the company, invalidcontact_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— list, picker, legal form hints, relation type catalog (read), organization contacts and deals: 120 requests per minute per user; create, edit, delete, link and unlink, relation type catalog and bank account writes: 60 per minute; the card: the shared heavy-request limit of an API token (120 per minute); custom fields: the custom field value write limit.
Endpoints
| Method | Path | Summary |
|---|---|---|
| GET | /v1/organizationsList the company 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]). Response: data.items + data.pagination. | List the company 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]). Response: data.items + data.pagination. |
| GET | /v1/organizations/lookupPick an organization by name or tax id (query: q up to 100 characters). Response: data.items — up to 20 {id, name, tax_id} records. | Pick an organization by name or tax id (query: q up to 100 characters). Response: data.items — up to 20 {id, name, tax_id} records. |
| GET | /v1/organizations/legal-formsLegal form hints: up to 20 most frequent legal_form values of the company. Response: data.items, an array of strings. | Legal form hints: up to 20 most frequent legal_form values of the company. Response: data.items, an array of strings. |
| POST | /v1/organizationsCreate an organization (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 is the card. 409 organization_tax_id_taken. | Create an organization (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 is the card. 409 organization_tax_id_taken. |
| GET | /v1/organizations/{organization}The organization card: fields and requisites, relation_type, custom fields with custom_fields_meta, contacts_count, (with deal.view) open_deals_count and open_deals_amount, (with organization_bank_account.view) bank_accounts. | The organization card: fields and requisites, relation_type, custom fields with custom_fields_meta, contacts_count, (with deal.view) open_deals_count and open_deals_amount, (with organization_bank_account.view) bank_accounts. |
| PATCH | /v1/organizations/{organization}Edit organization fields (only the ones sent). Response: the card. 409 organization_tax_id_taken. | Edit organization fields (only the ones sent). Response: the card. 409 organization_tax_id_taken. |
| DELETE | /v1/organizations/{organization}Delete an organization (soft; links are kept but read as null). | Delete an organization (soft; links are kept but read as null). |
| PUT | /v1/organizations/{organization}/custom-fieldsWrite the organization custom field values (body: custom_fields). Response: data.message and data.organization. | Write the organization custom field values (body: custom_fields). Response: data.message and data.organization. |
| GET | /v1/organizations/{organization}/contactsContacts of the organization (query: page, perPage 1–100). Response: data.items + data.pagination. Also needs contact.view. | Contacts of the organization (query: page, perPage 1–100). Response: data.items + data.pagination. Also needs contact.view. |
| POST | /v1/organizations/{organization}/contactsLink contacts in bulk (body: contact_ids — 1–100 ids). Response: data.linked_contact_ids. Also needs contact.update. | Link contacts in bulk (body: contact_ids — 1–100 ids). Response: data.linked_contact_ids. Also needs contact.update. |
| DELETE | /v1/organizations/{organization}/contacts/{contact}Unlink one contact from the organization. Also needs contact.update. | Unlink one contact from the organization. Also needs contact.update. |
| GET | /v1/organizations/{organization}/dealsDeals of the organization visible to the user (query: status = open|won|lost, page, perPage 1–100). Response: data.items + data.pagination. Needs deal.view and a plan with deals. | Deals of the organization visible to the user (query: status = open|won|lost, page, perPage 1–100). Response: data.items + data.pagination. Needs deal.view and a plan with deals. |
| POST | /v1/organizations/{organization}/bank-accountsAdd a bank account (body: bank_account, bank_name?, bank_bik?, currency?, is_default?, position?) — 201, data is the account. Also needs organization.update and organization_bank_account.view. | Add a bank account (body: bank_account, bank_name?, bank_bik?, currency?, is_default?, position?) — 201, data is the account. Also needs organization.update and organization_bank_account.view. |
| PATCH | /v1/organizations/{organization}/bank-accounts/{account}Edit a bank account (only the fields sent). Response: data is the account. 409 bank_account_default_conflict. Also needs organization.update and organization_bank_account.view. | Edit a bank account (only the fields sent). Response: data is the account. 409 bank_account_default_conflict. Also needs organization.update and organization_bank_account.view. |
| DELETE | /v1/organizations/{organization}/bank-accounts/{account}Delete a bank account — 204; the default flag moves to the earliest remaining account. Also needs organization.update and organization_bank_account.view. | Delete a bank account — 204; the default flag moves to the earliest remaining account. Also needs organization.update and organization_bank_account.view. |
| GET | /v1/organization-relation-typesThe relation type catalog in order (query: include_archived). Response: data.items with organizations_count. | The relation type catalog in order (query: include_archived). Response: data.items with organizations_count. |
| POST | /v1/organization-relation-typesCreate a relation type (body: name, color) — 201, data is the type. 422 relation_type_name_taken, relation_types_limit. | Create a relation type (body: name, color) — 201, data is the type. 422 relation_type_name_taken, relation_types_limit. |
| PUT | /v1/organization-relation-types/orderReorder the catalog (body: ids — every id of the company, archived included). Response: data.items. 422 relation_type_order_mismatch. | Reorder the catalog (body: ids — every id of the company, archived included). Response: data.items. 422 relation_type_order_mismatch. |
| PATCH | /v1/organization-relation-types/{relationType}Rename, recolor, archive or restore (body: name?, color?, is_archived?). Response: data is the type. | Rename, recolor, archive or restore (body: name?, color?, is_archived?). Response: data is the type. |
| DELETE | /v1/organization-relation-types/{relationType}Delete a relation type — 204. 409 relation_type_in_use (with organizations_count), 422 relation_type_system for a starter type. | Delete a relation type — 204. 409 relation_type_in_use (with organizations_count), 422 relation_type_system for a starter type. |
Examples
Create an organization
Request
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
}'Response
{
"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"
}
}Tax id already taken
Request
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" }'Response
{
"data": {
"message": "An organization with this tax id already exists.",
"code": "organization_tax_id_taken",
"existing_organization_id": 12
}
}List with a filter and sorting
Request
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"Response
{
"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 }
}
}Link contacts
Request
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] }'Response
{
"data": {
"message": "Contacts linked.",
"linked_contact_ids": [45, 47]
}
}Add a bank account
Request
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"
}'Response
{
"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"
}
}Create a relation type
Request
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" }'Response
{
"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"
}
}Relation type in use
Request
curl -X DELETE "https://api.aisar.app/v1/organization-relation-types/37" \
-H "Authorization: Bearer YOUR_API_TOKEN"Response
{
"data": {
"message": "The relation type is used by organizations; archive it instead.",
"code": "relation_type_in_use",
"organizations_count": 4
}
}Lookup by name or tax id
Request
curl "https://api.aisar.app/v1/organizations/lookup?q=120340567891" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"data": {
"items": [
{ "id": 12, "name": "Альфа Трейд", "tax_id": "120340567891" }
]
}
}Legal form hints
Request
curl "https://api.aisar.app/v1/organizations/legal-forms" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"data": {
"items": ["ТОО", "ИП", "АО"]
}
}Organization card
Request
curl "https://api.aisar.app/v1/organizations/12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"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"
}
}Update an organization
Request
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" }'Response
{
"data": {
"id": 12,
"name": "Альфа Трейд",
"phone": "+12025550143",
"address": "Example street 1",
"...": "...",
"updated_at": "2026-11-17T11:00:00.000000Z"
}
}Delete an organization
Request
curl -X DELETE "https://api.aisar.app/v1/organizations/12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"data": {
"message": "Organization deleted."
}
}Write organization custom fields
Request
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" } }'Response
{
"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" } }
}
}
}
}Organization contacts
Request
curl "https://api.aisar.app/v1/organizations/12/contacts?page=1&perPage=20" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"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 }
}
}Unlink a contact
Request
curl -X DELETE "https://api.aisar.app/v1/organizations/12/contacts/45" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"data": {
"message": "Contact unlinked."
}
}Open deals of the organization
Request
curl "https://api.aisar.app/v1/organizations/12/deals?status=open&perPage=20" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"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 }
}
}Update a bank account
Request
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" }'Response
{
"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"
}
}Delete a bank account (204)
Request
curl -X DELETE "https://api.aisar.app/v1/organizations/12/bank-accounts/5" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Relation type catalog
Request
curl "https://api.aisar.app/v1/organization-relation-types?include_archived=true" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"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" },
{ "...": "..." }
]
}
}Reorder relation types
Request
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] }'Response
{
"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" },
{ "...": "..." }
]
}
}Archive a relation type
Request
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 }'Response
{
"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"
}
}