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"
                    }
                }
            }
        ]
    }
}