> ## Documentation Index > Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt > Use this file to discover all available pages before exploring further. # Kommo API reference > API reference for the Kommo plugin in Corsair: every `kommo.api.*` operation with its input and output types, taken from the plugin's Zod schemas. > [!NOTE] > > **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling). ## Account ### get `account.get` The account itself: its name, subdomain, currency and country **Risk:** `read` ```ts theme={null} await corsair.kommo.api.account.get({}); ``` **Input:** *empty object* **Output** | Name | Type | Required | Description | | - | - | - | - | | `id` | `number` | Yes | — | | `name` | `string \| null` | No | — | | `subdomain` | `string \| null` | No | — | | `currency` | `string \| null` | No | — | | `country` | `string \| null` | No | — | | `created_at` | `number \| null` | No | — | | `_embedded` | `Record \| null` | No | — | *** ## Companies ### list `companies.list` Companies by owner or update date, paged **Risk:** `read` ```ts theme={null} await corsair.kommo.api.companies.list({ limit: 50 }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `page` | `number` | No | 1-based page. | | `limit` | `number` | No | Entities per page. Defaults to 250, which is the maximum. | | `query` | `string` | No | A search across the entity’s filled fields. | | `responsible_user_id` | `number` | No | — | | `updated_from` | `number` | No | Unix seconds. | | `updated_to` | `number` | No | Unix seconds. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `_page` | `number \| null` | No | — | | `_links` | `object \| null` | No | — | | `_embedded` | `object` | Yes | — | | `next_page` | `number \| null` | Yes | — | > [accordion] \_links full type > > ```ts theme={null} > { > self?: { > href?: string | null > } | null, > next?: { > href?: string | null > } | null > } | null > ``` > [accordion] \_embedded full type > > ```ts theme={null} > { > companies: { > id: number, > name?: string | null, > responsible_user_id?: number | null, > group_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > created_at?: number | null, > updated_at?: number | null, > is_deleted?: boolean | null, > account_id?: number | null, > custom_fields_values?: { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null, > _embedded?: { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > }[] > } > ``` *** ## Contacts ### create `contacts.create` Create contacts, each with a name or a first and last name, and custom fields **Risk:** `write` ```ts theme={null} await corsair.kommo.api.contacts.create({ contacts: [{ first_name: 'Jordan', last_name: 'Lee', custom_fields_values: [{ field_code: 'PHONE', values: [{ value: '+15550100' }] }] }] }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `contacts` | `object[]` | Yes | — | A contact needs a `name`, or a `first_name` and `last_name`. > [accordion] contacts full type > > ```ts theme={null} > { > name?: string, > first_name?: string, > last_name?: string, > responsible_user_id?: number, > custom_fields_values?: { > values?: Record[], > field_id?: number, > field_code?: string > }[] > }[] > ``` **Output** | Name | Type | Required | Description | | - | - | - | - | | `_embedded` | `object \| null` | No | — | > [accordion] \_embedded full type > > ```ts theme={null} > { > contacts: { > id: number, > name?: string | null, > first_name?: string | null, > last_name?: string | null, > responsible_user_id?: number | null, > group_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > created_at?: number | null, > updated_at?: number | null, > is_deleted?: boolean | null, > account_id?: number | null, > custom_fields_values?: { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null, > _embedded?: { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > }[] > } | null > ``` *** ### get `contacts.get` One contact with its custom field values **Risk:** `read` ```ts theme={null} await corsair.kommo.api.contacts.get({ contactId: 30012345 }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `contactId` | `number` | Yes | The Kommo entity ID. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `id` | `number` | Yes | — | | `name` | `string \| null` | No | — | | `first_name` | `string \| null` | No | — | | `last_name` | `string \| null` | No | — | | `responsible_user_id` | `number \| null` | No | — | | `group_id` | `number \| null` | No | — | | `created_by` | `number \| null` | No | — | | `updated_by` | `number \| null` | No | — | | `created_at` | `number \| null` | No | — | | `updated_at` | `number \| null` | No | — | | `is_deleted` | `boolean \| null` | No | — | | `account_id` | `number \| null` | No | — | | `custom_fields_values` | `object[] \| null` | No | — | | `_embedded` | `object \| null` | No | — | > [accordion] custom\_fields\_values full type > > ```ts theme={null} > { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null > ``` > [accordion] \_embedded full type > > ```ts theme={null} > { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > ``` *** ### list `contacts.list` Contacts by owner or update date, paged, optionally with their leads **Risk:** `read` ```ts theme={null} await corsair.kommo.api.contacts.list({ limit: 50, with: ['leads'] }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `page` | `number` | No | 1-based page. | | `limit` | `number` | No | Entities per page. Defaults to 250, which is the maximum. | | `query` | `string` | No | A search across the entity’s filled fields. | | `with` | `leads[]` | No | Embed the leads each contact is linked to. | | `responsible_user_id` | `number` | No | — | | `updated_from` | `number` | No | Unix seconds. | | `updated_to` | `number` | No | Unix seconds. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `_page` | `number \| null` | No | — | | `_links` | `object \| null` | No | — | | `_embedded` | `object` | Yes | — | | `next_page` | `number \| null` | Yes | — | > [accordion] \_links full type > > ```ts theme={null} > { > self?: { > href?: string | null > } | null, > next?: { > href?: string | null > } | null > } | null > ``` > [accordion] \_embedded full type > > ```ts theme={null} > { > contacts: { > id: number, > name?: string | null, > first_name?: string | null, > last_name?: string | null, > responsible_user_id?: number | null, > group_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > created_at?: number | null, > updated_at?: number | null, > is_deleted?: boolean | null, > account_id?: number | null, > custom_fields_values?: { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null, > _embedded?: { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > }[] > } > ``` *** ### update `contacts.update` Change fields on one or more contacts, each named by its `id` **Risk:** `write` ```ts theme={null} await corsair.kommo.api.contacts.update({ contacts: [{ id: 30012345, first_name: 'Jordy' }] }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `contacts` | `object[]` | Yes | Each contact carries its `id` and the fields to change. | > [accordion] contacts full type > > ```ts theme={null} > { > name?: string, > first_name?: string, > last_name?: string, > responsible_user_id?: number, > custom_fields_values?: { > values?: Record[], > field_id?: number, > field_code?: string > }[], > id: number > }[] > ``` **Output** | Name | Type | Required | Description | | - | - | - | - | | `_embedded` | `object \| null` | No | — | > [accordion] \_embedded full type > > ```ts theme={null} > { > contacts: { > id: number, > name?: string | null, > first_name?: string | null, > last_name?: string | null, > responsible_user_id?: number | null, > group_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > created_at?: number | null, > updated_at?: number | null, > is_deleted?: boolean | null, > account_id?: number | null, > custom_fields_values?: { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null, > _embedded?: { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > }[] > } | null > ``` *** ## Leads ### create `leads.create` Create up to 250 leads in one request, each with its price, stage, pipeline and custom fields **Risk:** `write` ```ts theme={null} await corsair.kommo.api.leads.create({ leads: [{ name: 'Acme renewal', price: 5000, pipeline_id: 12215168, custom_fields_values: [{ field_id: 1928052, values: [{ value: 'Diagnostic', enum_id: 1669868 }] }] }] }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `leads` | `object[]` | Yes | At most 250 in one request. A lead without `status_id` or `pipeline_id` lands in the first stage of the main pipeline. | Posts an array of up to 250. A lead without `pipeline_id` or `status_id` lands in the first stage of the main pipeline. > [accordion] leads full type > > ```ts theme={null} > { > name: nonoptional, > price?: number, > status_id?: number, > pipeline_id?: number, > responsible_user_id?: number, > loss_reason_id?: number, > custom_fields_values?: { > values?: Record[], > field_id?: number, > field_code?: string > }[] > }[] > ``` **Output** | Name | Type | Required | Description | | - | - | - | - | | `_embedded` | `object \| null` | No | — | > [accordion] \_embedded full type > > ```ts theme={null} > { > leads: { > id: number, > name?: string | null, > price?: number | null, > responsible_user_id?: number | null, > group_id?: number | null, > status_id?: number | null, > pipeline_id?: number | null, > loss_reason_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > created_at?: number | null, > updated_at?: number | null, > closed_at?: number | null, > closest_task_at?: number | null, > is_deleted?: boolean | null, > score?: number | null, > account_id?: number | null, > labor_cost?: number | null, > is_price_computed?: boolean | null, > custom_fields_values?: { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null, > _embedded?: { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > }[] > } | null > ``` *** ### get `leads.get` One lead with its custom field values and, on request, its contacts, loss reason and source **Risk:** `read` ```ts theme={null} await corsair.kommo.api.leads.get({ leadId: 20024930, with: ['contacts', 'loss_reason'] }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `leadId` | `number` | Yes | The Kommo entity ID. | | `with` | `(contacts \| loss_reason \| catalog_elements \| source)[]` | No | — | **Output** | Name | Type | Required | Description | | - | - | - | - | | `id` | `number` | Yes | — | | `name` | `string \| null` | No | — | | `price` | `number \| null` | No | — | | `responsible_user_id` | `number \| null` | No | — | | `group_id` | `number \| null` | No | — | | `status_id` | `number \| null` | No | — | | `pipeline_id` | `number \| null` | No | — | | `loss_reason_id` | `number \| null` | No | — | | `created_by` | `number \| null` | No | — | | `updated_by` | `number \| null` | No | — | | `created_at` | `number \| null` | No | — | | `updated_at` | `number \| null` | No | — | | `closed_at` | `number \| null` | No | — | | `closest_task_at` | `number \| null` | No | — | | `is_deleted` | `boolean \| null` | No | — | | `score` | `number \| null` | No | — | | `account_id` | `number \| null` | No | — | | `labor_cost` | `number \| null` | No | — | | `is_price_computed` | `boolean \| null` | No | — | | `custom_fields_values` | `object[] \| null` | No | — | | `_embedded` | `object \| null` | No | — | > [accordion] custom\_fields\_values full type > > ```ts theme={null} > { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null > ``` > [accordion] \_embedded full type > > ```ts theme={null} > { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > ``` *** ### list `leads.list` Leads by pipeline, stage, owner or date, paged 250 at a time; `next_page` says whether another exists **Risk:** `read` ```ts theme={null} await corsair.kommo.api.leads.list({ limit: 50, pipeline_id: 12215168, with: ['contacts'], order_by: 'created_at', order_direction: 'desc' }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `page` | `number` | No | 1-based page. | | `limit` | `number` | No | Entities per page. Defaults to 250, which is the maximum. | | `query` | `string` | No | A search across the entity’s filled fields. | | `with` | `(contacts \| loss_reason \| catalog_elements \| source)[]` | No | Embed these extra details on each lead. | | `pipeline_id` | `number` | No | — | | `status_id` | `number` | No | A stage. Needs `pipeline_id`, the pipeline the stage is in. | | `responsible_user_id` | `number` | No | — | | `created_from` | `number` | No | Unix seconds. | | `created_to` | `number` | No | Unix seconds. | | `updated_from` | `number` | No | Unix seconds. | | `updated_to` | `number` | No | Unix seconds. | | `order_by` | `created_at \| updated_at \| id` | No | Sort field. Needs `order_direction`. | | `order_direction` | `asc \| desc` | No | Sort direction. Needs `order_by`. | Pages by number, 250 at most. `next_page` is null on the last page. Date filters are Unix seconds. A `status_id` filter needs its `pipeline_id`; Kommo allows one stage in one pipeline per request. `order_by` and `order_direction` go together. **Output** | Name | Type | Required | Description | | - | - | - | - | | `_page` | `number \| null` | No | — | | `_links` | `object \| null` | No | — | | `_embedded` | `object` | Yes | — | | `next_page` | `number \| null` | Yes | The page after this one while Kommo says another exists; null on the last page. | > [accordion] \_links full type > > ```ts theme={null} > { > self?: { > href?: string | null > } | null, > next?: { > href?: string | null > } | null > } | null > ``` > [accordion] \_embedded full type > > ```ts theme={null} > { > leads: { > id: number, > name?: string | null, > price?: number | null, > responsible_user_id?: number | null, > group_id?: number | null, > status_id?: number | null, > pipeline_id?: number | null, > loss_reason_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > created_at?: number | null, > updated_at?: number | null, > closed_at?: number | null, > closest_task_at?: number | null, > is_deleted?: boolean | null, > score?: number | null, > account_id?: number | null, > labor_cost?: number | null, > is_price_computed?: boolean | null, > custom_fields_values?: { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null, > _embedded?: { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > }[] > } > ``` *** ### update `leads.update` Change fields on one or more leads, each named by its `id`; a field left out is untouched **Risk:** `write` ```ts theme={null} await corsair.kommo.api.leads.update({ leads: [{ id: 20024930, price: 7000, status_id: 94386188 }] }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `leads` | `object[]` | Yes | Each lead carries its `id` and the fields to change. | PATCH with an array, each lead carrying its `id`. A field left out is untouched. > [accordion] leads full type > > ```ts theme={null} > { > name?: string, > price?: number, > status_id?: number, > pipeline_id?: number, > responsible_user_id?: number, > loss_reason_id?: number, > custom_fields_values?: { > values?: Record[], > field_id?: number, > field_code?: string > }[], > id: number > }[] > ``` **Output** | Name | Type | Required | Description | | - | - | - | - | | `_embedded` | `object \| null` | No | — | > [accordion] \_embedded full type > > ```ts theme={null} > { > leads: { > id: number, > name?: string | null, > price?: number | null, > responsible_user_id?: number | null, > group_id?: number | null, > status_id?: number | null, > pipeline_id?: number | null, > loss_reason_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > created_at?: number | null, > updated_at?: number | null, > closed_at?: number | null, > closest_task_at?: number | null, > is_deleted?: boolean | null, > score?: number | null, > account_id?: number | null, > labor_cost?: number | null, > is_price_computed?: boolean | null, > custom_fields_values?: { > field_id?: number | null, > field_name?: string | null, > field_code?: string | null, > field_type?: string | null, > values?: { > value: any, > enum_id?: number | null, > enum_code?: string | null > }[] | null, > is_computed?: boolean | null > }[] | null, > _embedded?: { > tags?: { > id?: number | null, > name?: string | null, > color?: string | null > }[] | null, > contacts?: { > id: number > }[] | null, > companies?: { > id: number > }[] | null > } | null > }[] > } | null > ``` *** ## Pipelines ### list `pipelines.list` The lead pipelines with their stages, which is where a lead’s `pipeline_id` and `status_id` come from **Risk:** `read` ```ts theme={null} await corsair.kommo.api.pipelines.list({}); ``` **Input:** *empty object* Where a lead’s `pipeline_id` and `status_id` come from. **Output** | Name | Type | Required | Description | | - | - | - | - | | `_embedded` | `object` | Yes | — | > [accordion] \_embedded full type > > ```ts theme={null} > { > pipelines: { > id: number, > name?: string | null, > sort?: number | null, > is_main?: boolean | null, > is_unsorted_on?: boolean | null, > is_archive?: boolean | null, > account_id?: number | null, > _embedded?: { > statuses?: { > id: number, > name?: string | null, > sort?: number | null, > color?: string | null, > is_editable?: boolean | null, > pipeline_id?: number | null > }[] | null > } | null > }[] > } > ``` *** ## Tasks ### create `tasks.create` Create tasks against a lead, contact or company; every task needs a `complete_till` deadline **Risk:** `write` ```ts theme={null} await corsair.kommo.api.tasks.create({ tasks: [{ entity_id: 20024930, entity_type: 'leads', text: 'Call about the quote', complete_till: Math.floor(Date.now() / 1000) + 86400 }] }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `tasks` | `object[]` | Yes | — | `complete_till` is required and is Unix seconds. > [accordion] tasks full type > > ```ts theme={null} > { > entity_id: number, > entity_type: leads | contacts | companies, > text: string, > complete_till: number, > task_type_id?: number, > responsible_user_id?: number > }[] > ``` **Output** | Name | Type | Required | Description | | - | - | - | - | | `_embedded` | `object \| null` | No | — | > [accordion] \_embedded full type > > ```ts theme={null} > { > tasks: { > id: number, > entity_id?: number | null, > entity_type?: string | null, > is_completed?: boolean | null, > task_type_id?: number | null, > text?: string | null, > result?: { > text?: string | null, > id?: number | null > } | any[] | null, > responsible_user_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > complete_till?: number | null, > created_at?: number | null, > updated_at?: number | null, > account_id?: number | null > }[] > } | null > ``` *** ### list `tasks.list` Tasks by entity, owner or completion, paged; the deadline is a Unix timestamp **Risk:** `read` ```ts theme={null} await corsair.kommo.api.tasks.list({ entity_type: 'leads', is_completed: false }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `page` | `number` | No | 1-based page. | | `limit` | `number` | No | Entities per page. Defaults to 250, which is the maximum. | | `query` | `string` | No | A search across the entity’s filled fields. | | `entity_type` | `leads \| contacts \| companies` | No | Only tasks on this kind of entity. | | `entity_id` | `number` | No | — | | `responsible_user_id` | `number` | No | — | | `is_completed` | `boolean` | No | True for completed tasks, false for open ones. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `_page` | `number \| null` | No | — | | `_links` | `object \| null` | No | — | | `_embedded` | `object` | Yes | — | | `next_page` | `number \| null` | Yes | — | > [accordion] \_links full type > > ```ts theme={null} > { > self?: { > href?: string | null > } | null, > next?: { > href?: string | null > } | null > } | null > ``` > [accordion] \_embedded full type > > ```ts theme={null} > { > tasks: { > id: number, > entity_id?: number | null, > entity_type?: string | null, > is_completed?: boolean | null, > task_type_id?: number | null, > text?: string | null, > result?: { > text?: string | null, > id?: number | null > } | any[] | null, > responsible_user_id?: number | null, > created_by?: number | null, > updated_by?: number | null, > complete_till?: number | null, > created_at?: number | null, > updated_at?: number | null, > account_id?: number | null > }[] > } > ``` *** ## Users ### list `users.list` The account’s users, for looking up a responsible user ID **Risk:** `read` ```ts theme={null} await corsair.kommo.api.users.list({}); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `limit` | `number` | No | — | | `page` | `number` | No | — | **Output** | Name | Type | Required | Description | | - | - | - | - | | `_embedded` | `object` | Yes | — | | `_page` | `number \| null` | No | — | > [accordion] \_embedded full type > > ```ts theme={null} > { > users: { > id: number, > name?: string | null, > email?: string | null, > lang?: string | null, > rights?: Record | null > }[] > } > ``` *** This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.