Companies
In this section, we will describe all available methods for the Company entity.
Table of Contents
Companies list
Method
GET /api/v4/companies
Description
This method allows to get a list of companies in the account.
Limitations
The method is available in correspondence to the user rights.
GET parameters
Parameter | Data type | Description |
---|---|---|
with | string | This parameter takes a string that may consist of several values separated by commas. This method supports the following parameters. |
page | int | Sample page |
limit | int | The number of the entities returned in the response to one request (limit – 250) |
query | string|int | Search query (will perform a search by custom fields values) |
order | object | List elements sorting Fields available to sort by: updated_at, id. Values available to sort by: asc, desc. An example: /api/v4/companies?order[updated_at]=asc |
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | The user is not authorized |
Response parameters
The method returns the company models collection. The properties of a company model are listed below.
Parameter | Data type | Description |
---|---|---|
id | int | Company ID |
name | string | Company name |
responsible_user_id | int | Company responsible user ID |
group_id | int | Group ID of the company responsible user |
created_by | int | Id of the user who created the company |
updated_by | int | Id of the user who updated the company |
created_at | int | The time and date the company was created in the format of Unix Timestamp |
updated_at | int | The time and date the company was updated in the format of Unix Timestamp |
closest_task_at | int | Date of the closest open task in the format of Unix Timestamp |
custom_fields_values | array|null | An array of the current company custom fields’ values |
account_id | int | Account ID where the company is located in |
_embedded | object | Embedded entities data |
_embedded[tags] | array | Company tags data array |
_embedded[tags][0] | object | Company tag model |
_embedded[tags][0][id] | int | Tag ID |
_embedded[tags][0][name] | string | Tag name |
_embedded[contacts] | array | GET parameter “with” is required. Linked contacts data array |
_embedded[contacts][0] | object | Linked contact data |
_embedded[contacts][0][id] | int | Linked contact ID |
_embedded[customers] | array | GET parameter “with” is required. Linked customers data array |
_embedded[customers][0] | object | Linked customer data |
_embedded[customers][0][id] | int | Linked customer ID |
_embedded[leads] | array | GET parameter “with” is required. Linked leads data array |
_embedded[leads][0] | object | Linked lead data |
_embedded[leads][0][id] | int | Linked lead ID |
_embedded[catalog_elements] | array | GET parameter “with” is required. Linked lists’ elements data array |
_embedded[catalog_elements][0] | object | Linked list element data |
_embedded[catalog_elements][0][id] | int | Linked element ID |
_embedded[catalog_elements][0][metadata] | object | Meta-data of the element |
_embedded[catalog_elements][0][quantity] | int | Linked elements quantity |
_embedded[catalog_elements][0][catalog_id] | int | ID of the linked element’s list |
Response example
{
"_page": 1,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/companies?limit=2&page=1"
},
"next": {
"href": "https://example.kommo.com/api/v4/companies?limit=2&page=2"
}
},
"_embedded": {
"companies": [
{
"id": 7767077,
"name": "Peter's Company",
"responsible_user_id": 504141,
"group_id": 0,
"created_by": 504141,
"updated_by": 504141,
"created_at": 1586359618,
"updated_at": 1586359618,
"closest_task_at": null,
"custom_fields_values": null,
"account_id": 28805383,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/companies/7767077"
}
},
"_embedded": {
"tags": []
}
},
{
"id": 7767457,
"name": "Example",
"responsible_user_id": 504141,
"group_id": 0,
"created_by": 504141,
"updated_by": 504141,
"created_at": 1586359618,
"updated_at": 1586359618,
"closest_task_at": null,
"custom_fields_values": null,
"account_id": 28805383,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/companies/7767457"
}
},
"_embedded": {
"tags": []
}
}
]
}
}
Parameters for GET-parameters “with”
Parameter | Description |
---|---|
catalog_elements | Adds lists elements linked to the company into the response |
leads | Adds info on the leads linked to the company into the response |
customers | Adds info on the customers linked to the company into the response |
contacts | Adds info on the contacts linked to the company into the response |
Getting a company by its ID
Method
GET /api/v4/companies/{id}
Description
This method allows to get a particular company data by its ID.
Limitations
The method is available in correspondence to the user rights.
GET parameters
Parameter | Data type | Description |
---|---|---|
with | string | This parameter takes a string that may consist of several values separated by commas. This method supports the following parameters. |
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
204 | The company with the specified ID does not exist |
401 | The user is not authorized |
Response parameters
The method returns a company model. The properties of the company model are listed below.
Parameter | Data type | Description |
---|---|---|
id | int | Company ID |
name | string | Company name |
responsible_user_id | int | Company responsible user ID |
group_id | int | Group ID of the company responsible user |
created_by | int | Id of the user who created the company |
updated_by | int | Id of the user who updated the company |
created_at | int | The time and date the company was created in the format of Unix Timestamp |
updated_at | int | The time and date the company was updated in the format of Unix Timestamp |
closest_task_at | int | Date of the closest open task in the format of Unix Timestamp |
custom_fields_values | array|null | An array of the current company custom fields’ values |
account_id | int | Account ID where the company is located in |
_embedded | object | Embedded entities data |
_embedded[tags] | array | Company tags data array |
_embedded[tags][0] | object | Company tag model |
_embedded[tags][0][id] | int | Tag ID |
_embedded[tags][0][name] | string | Tag name |
_embedded[contacts] | array | GET parameter “with” is required. Linked contacts data array |
_embedded[contacts][0] | object | Linked contact data |
_embedded[contacts][0][id] | int | Linked contact ID |
_embedded[customers] | array | GET parameter “with” is required. Linked customers data array |
_embedded[customers][0] | object | Linked customer data |
_embedded[customers][0][id] | int | Linked customer ID |
_embedded[leads] | array | GET parameter “with” is required. Linked leads data array |
_embedded[leads][0] | object | Linked lead data |
_embedded[leads][0][id] | int | Linked lead ID |
_embedded[catalog_elements] | array | GET parameter “with” is required. Linked lists’ elements data array |
_embedded[catalog_elements][0] | object | Linked list element data |
_embedded[catalog_elements][0][id] | int | Linked element ID |
_embedded[catalog_elements][0][metadata] | object | Meta-data of the element |
_embedded[catalog_elements][0][quantity] | int | Linked elements quantity |
_embedded[catalog_elements][0][catalog_id] | int | ID of the linked element’s list |
Response example
{
"id": 1,
"name": "Acme Co.",
"responsible_user_id": 504141,
"group_id": 0,
"created_by": 504141,
"updated_by": 504141,
"created_at": 1586359618,
"updated_at": 1586359618,
"closest_task_at": null,
"custom_fields_values": [
{
"field_id": 3,
"field_name": "Work phone",
"field_code": "PHONE",
"field_type": "multitext",
"values": [
{
"value": "+14155551234",
"enum_id": 1,
"enum": "WORK"
}
]
}
],
"account_id": 28805383,
"_links": {
"self": {
"href": "https://exmaple.kommo.com/api/v4/companies/1"
}
},
"_embedded": {
"tags": []
}
}
Parameters for GET-parameters “with”
Parameter | Description |
---|---|
catalog_elements | Adds lists elements linked to the company into the response |
leads | Adds info on the leads linked to the company into the response |
customers | Adds info on the customers linked to the company into the response |
contacts | Adds info on the contacts linked to the company into the response |
Adding companies
Method
POST /api/v4/companies
Description
This method allows adding multiple or singular companies into the account.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
No fields are mandatory
Parameter | Data type | Description |
---|---|---|
name | string | Company name |
responsible_user_id | int | Company responsible user ID |
created_by | int | Id of the user who created the company |
updated_by | int | Id of the user who updated the company |
created_at | int | The time and date the company was created in the format of Unix Timestamp |
updated_at | int | The time and date the company was updated in the format of Unix Timestamp |
custom_fields_values | array | An array of the current company custom fields’ values. Examples of custom fields structure |
_embedded | object | Embedded entities data |
_embedded[tags] | array | Company tags data array |
_embedded[tags][0] | object | Company tag model |
_embedded[tags][0][id] | int | Tag ID |
_embedded[tags][0][name] | string | Tag name |
request_id | string | The field that will be returned unchanged in the response and will not be saved. Is not a mandatory field |
An example of the request
[
{
"name": "Acme Co.",
"custom_fields_values": [
{
"field_code": "PHONE",
"values": [
{
"value": "+14155551234",
"enum_code": "WORK"
}
]
}
]
}
]
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Companies have been created successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns a collection of created companies.
Response example
{
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/companies"
}
},
"_embedded": {
"companies": [
{
"id": 11090825,
"request_id": "0",
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/companies/11090825"
}
}
}
]
}
}
Updating companies
Method
PATCH /api/v4/companies
Description
This method allows updating multiple companies.
To update a singular company, you can add the company ID into the method URL (/api/v4/companies/{id}).
When updating multiple companies, an array of company objects is passed. In the case of a singular company, the company model is passed.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
No fields are mandatory
Parameter | Data type | Description |
---|---|---|
name | string | Company name |
responsible_user_id | int | Company responsible user ID |
created_by | int | Id of the user who created the company |
updated_by | int | Id of the user who updated the company |
created_at | int | The time and date the company was created in the format of Unix Timestamp |
updated_at | int | The time and date the company was updated in the format of Unix Timestamp |
custom_fields_values | array | An array of the current company custom fields’ values. Examples of custom fields structure |
_embedded | object | Embedded entities data |
_embedded[tags] | array | Company tags data array |
_embedded[tags][0] | object | Company tag model |
_embedded[tags][0][id] | int | Tag ID |
_embedded[tags][0][name] | string | Tag name |
request_id | string | The field will be returned unchanged in the response and will not be saved. Is not a mandatory field |
An example of the request
[
{
"id": 11090825,
"name": "New company name",
"custom_fields_values": [
{
"field_code": "EMAIL",
"values": [
{
"value": "test@example.com",
"enum_code": "WORK"
}
]
}
]
}
]
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Companies have been updated successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns a collection of updated companies.
Response example
{
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/companies"
}
},
"_embedded": {
"companies": [
{
"id": 11090825,
"name": "New company name",
"updated_at": 1590998669,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/companies/11090825"
}
}
}
]
}
}