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

Method is available in correspondense to the user rights.

GET parameters

Parameter Data type Description
with string This parameter takes a string which 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 of one request (limit – 250)
query string|int Search query (will perform a search by custom fields values)
filter object Filter. Filters are described in detail in the separate article
order object List elements sorting
Fields available to sort by: created_at, 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 User is not authorized

Response parameters

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 last
created_at int Company creation date in the format of Unix Timestamp
updated_at int Company update date 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.amocrm.com/api/v4/companies?limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.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.amocrm.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": 1586360394,
                "updated_at": 1586360394,
                "closest_task_at": null,
                "custom_fields_values": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.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

Method is available in correspondense to the user rights.

GET parameters

Parameter Data type Description
with string This parameter takes a string which 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 User is not authorized

Response parameters

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 last
created_at int Company creation date in the format of Unix Timestamp
updated_at int Company update date 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": 1582117331,
    "updated_at": 1586361223,
    "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.amocrm.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

Method is available in correspondense 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 last
created_at int Company creation date in the format of Unix Timestamp
updated_at int Company update date 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 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 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of created companies.

Response example

        
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/companies"
        }
    },
    "_embedded": {
        "companies": [
            {
                "id": 11090825,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.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 case with a singular company, the company model is passed.

Limitations

Method is available in correspondense 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 last
created_at int Company creation date in the format of Unix Timestamp
updated_at int Company update date 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 Field that 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 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of updated companies.

Response example

        
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/companies"
        }
    },
    "_embedded": {
        "companies": [
            {
                "id": 11090825,
                "name": "New company name",
                "updated_at": 1590998669,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/companies/11090825"
                    }
                }
            }
        ]
    }
}