COMPANIES

A company is completely analogous to the essence of "contact". It consists of a predefined set of fields and additional accounts created by the administrator of the account. Each company may participate in one or more leads or may not be associated with any one at all.

E-mail and phone are used as identifiers in conjunction with other systems

Each company can be assigned a responsibility to differentiate access rights between employees of the account.


Adding and updating companies

The method allows you to add companies one by one or batch, and also update data on existing companies.

URL of the method

POST / api / v2 / companies

Parameters
Parameter Type Description
add array List of added companies
update array The list of existing companies that will be changed.
All the parameters described for adding are also relevant for updating
add/name
require
string Company name
add/created_at timestamp Date and time the company was created
add/updated_at timestamp Date and time of the change in the company
add/responsible_user_id int ID of the person responsible for the company
add/created_by int ID of the user who created the company
add/tags string Tags that are attached to the company. They are specified by an integral string variable, inside the line they are separated by commas.
add/leads_id string Leads that are tied to the company. The list of ids is comma separated.
add/customers_id string Customers tied to the company. The list of ids is comma separated.
add/contacts_id string Contacts that are attached to the company.he list of ids is comma separated.
add/custom_fields array An array of additional entity fields
add/custom_fields//id int ID of the additional field of the entity
add/custom_fields//values array Array of values
add/custom_fields//values//value string The value of the additional field
add/custom_fields//values//enum string Early identifier of pre-selected option for list or multi-selection
add/custom_fields//values//subtype string The type of the element to change the custom field of the address type. Attention, all unspecified types will be erased.
update/id
require
int ID of the company to which the changes will be made
update/updated_at
require
timestamp Date and time of the change
update/unlink array An array containing information to detach a company from other entity elements.
update/unlink/contacts_id array Array id of unlinked contacts
update/unlink/leads_id array Array id of the leads to be detached
update/unlink/customers_id array Array of ID's of detached customers

Here is an example of a request to add a new company.

Example request
  1. {
  2.    add: [
  3.       {
  4.          name: "Company LLC",
  5.          responsible_user_id: "504141",
  6.          created_by: "504141",
  7.          created_at: "1509051600",
  8.          tags: "real_estate, development, rent",
  9.          leads_id: [
  10.             "45615",
  11.             "43510"
  12.          ],
  13.          custom_fields: [
  14.             {
  15.                id: "4396817",
  16.                values: [
  17.                   {
  18.                      value: "5"
  19.                   }
  20.                ]
  21.             },
  22.             {
  23.                id: "4396818",
  24.                values: [
  25.                   {
  26.                      value: "19999517535",
  27.                      enum: "WORK"
  28.                   },
  29.                   {
  30.                      value: "19991237895",
  31.                      enum: "MOB"
  32.                   }
  33.                ]
  34.             },
  35.             {
  36.                id: "4396819",
  37.                values: [
  38.                   {
  39.                      value: "company@company.moc",
  40.                      enum: "WORK"
  41.                   }
  42.                ]
  43.             },
  44.             {
  45.                id: "4396820",
  46.                values: [
  47.                   {
  48.                      value: "company.moc"
  49.                   }
  50.                ]
  51.             },
  52.             {
  53.                id: "4400115",
  54.                values: [
  55.                   {
  56.                      value: "Madison st, 2",
  57.                      subtype: "address_line_1"
  58.                   },
  59.                   {
  60.                      value: "Washington",
  61.                      subtype: "city"
  62.                   },
  63.                   {
  64.                      value: "20011",
  65.                      subtype: "zip"
  66.                   },
  67.                   {
  68.                      value: "US",
  69.                      subtype: "country"
  70.                   }
  71.                ]
  72.             }
  73.          ]
  74.       }
  75.    ]
  76. }

Here is an example of a request to update a company.

Example request
  1. {
  2.    update: [
  3.       {
  4.          id: "41389",
  5.          updated_at: "1508965200",
  6.          custom_fields: [
  7.             {
  8.                id: "315289",
  9.                values: [
  10.                   {
  11.                      value: "example.moc",
  12.                      enum: "WEB"
  13.                   }
  14.                ]
  15.             }
  16.          ]
  17.       }
  18.    ]
  19. }
Response parameters
Parameter Description
id The unique identifier of the new entity element
request_id The unique identifier of the entity in the client program, if request_id is not passed in the request, it is automatically generated
_links Array containing information about the request
_links/self An array containing information about the current request
_links/self/href Relative URL of the current request
_links/self/method The method of the current request
_embedded An array containing information adjacent to the query
_embedded/items An array containing information for each individual element

Response Headers contains the following headers:

  • Content-Type: application / hal + json

  • Runtime-Timestamp: 1508320306

Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/companies",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1099264,
  12.             _links: {
  13.                self: {
  14.                   href: "/api/v2/companies?id=1099264",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }
Example integration

To add a company, you need to describe an array containing information about the company, and put it into an array of the following kind: $companies ['add']. Our API also supports the simultaneous addition of several companies at once. To do this, we put several arrays into the $companies ['add'] array, each of which describes the necessary data to create the corresponding contact.

  1. $companies['add']=array(
  2.    array(
  3.       'name' => ''Company LLC'',
  4.       'responsible_user_id' => 504141,
  5.       'created_by' => 504141,
  6.       'created_at' => "1509051600",
  7.       'tags' => "real_estate, development, rent",
  8.       'leads_id' => array(
  9.          "45615",
  10.          "43510"
  11.       ),
  12.       'custom_fields' => array(
  13.          array(
  14.             'id' => 4396818,
  15.             'values' => array(
  16.                array(
  17.                   'value' => "19999517535",
  18.                   'enum' => "WORK"
  19.                ),
  20.                array(
  21.                   'value' => "19991237895",
  22.                   'enum' => "MOB"
  23.                )
  24.             )
  25.          ),
  26.          array(
  27.             'id' => 4396819,
  28.             'values' => array(
  29.                array(
  30.                   'value' => "company@company.moc",
  31.                   'enum' => "WORK"
  32.                )
  33.             )
  34.          ),
  35.          array(
  36.             'id' => 4400115,
  37.             'values' => array(
  38.                array(
  39.                   'value' => "Madison st., 2",
  40.                   'subtype' => "address_line_1"
  41.                ),
  42.                array(
  43.                   value: "Washington",
  44.                   subtype: "city"
  45.                ),
  46.                array(
  47.                   value: "20011",
  48.                   subtype: "zip"
  49.                ),
  50.                array(
  51.                   value: "US",
  52.                   subtype: "country"
  53.                )
  54.             )
  55.          ),
  56.          array(
  57.             'id' => 3789654,
  58.             'values' => array(
  59.                "2615948",
  60.                "2648159",
  61.                "2653867"
  62.             )
  63.          )
  64.       )
  65.    )
  66. )
  67. );
  68. /* Now prepare the data needed to query the server */
  69. $subdomain='test'; #Our account - a subdomain
  70. #Generate a link for the request
  71. $link='https://'.$subdomain.'.amocrm.com/api/v2/companies';
  72. /* We need to initiate a request to the server. We use the cURL library (supplied as PHP). More about
  73. working with this
  74. library you can read in the manual. */
  75. $curl=curl_init(); #Save the cURL session descriptor
  76. #Set the necessary options for the cURL session
  77. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  78. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  79. curl_setopt($curl,CURLOPT_URL,$link);
  80. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  81. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($companies));
  82. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  83. curl_setopt($curl,CURLOPT_HEADER,false);
  84. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  85. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  86. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  87. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  88. $out=curl_exec($curl); #Initialize a request to the API and save the response to a variable
  89. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  90. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  91. $code=(int)$code;
  92. $errors=array(
  93.   301=>'Moved permanently',
  94.   400=>'Bad request',
  95.   401=>'Unauthorized',
  96.   403=>'Forbidden',
  97.   404=>'Not found',
  98.   500=>'Internal server error',
  99.   502=>'Bad gateway',
  100.   503=>'Service unavailable'
  101. );
  102. try
  103. {
  104.   #If the response code is not 200 or 204, we return an error message
  105.  if($code!=200 && $code!=204)
  106.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  107. }
  108. catch(Exception $E)
  109. {
  110.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  111. }
  112. /*
  113.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  114.  We will have to translate the answer into a format that PHP understands
  115.  */
  116. $Response=json_decode($out,true);
  117. $Response=$Response[_embedded']['items'];
  118. $output=''The ID of the added contacts:'.PHP_EOL;
  119. foreach($Response as $v)
  120.  if(is_array($v))
  121.    $output.=$v['id'].PHP_EOL;
  122. return $output;

List of companies

Method for obtaining a list of companies with the ability to filter and paginate. Restriction on data returned on one page (offset) - 500 companies.

URL of the method

GET / api / v2 / companies

GET parameters
Parameter Description
limit_rows Number of selectable rows (system limit 500)
limit_offsetShift the selection (from which row to choose). Works only if limit_rows is specified
id Select the element with the given ID (If this parameter is specified, all the others are ignored). Can be sent as an array consisting of several IDs
query Search query (Searches for the filled fields of the entity)
responsible_user_id Additional search filter, by responsible user (Can be transferred as an array)

You can also send an additional HTTP header IF-MODIFIED-SINCE, which specifies the date in the D format, d M Y H: i: s. When this header is transmitted, the transactions changed later than this date will be returned. The title should be sent in the UTC time zone.

  1. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2017 07:07:23 UTC'));
Description of response parameters
Parameter Type Description
id int Unique company identifier
name string Company name
responsible_user_id int id of the responsible user
created_by int id of the user who created the company
created_at timestamp Date and time the company was created
updated_at timestamp Time and date of the change in the company
account_id int id of the account on which the company is established
updated_by int id of the user who updated the company
group_id int id of the group in which the user is responsible for the given company
contacts array An array containing information about contacts that are attached to this company
contacts/id int id of the contact that is attached to this company
leads array An array containing information about leads that are attached to this company
leads/id int id of the lead that is attached to this company
closest_task_at int Time of the nearest task for this company
tags array An array containing information on tags attached to the company
tags/id int id of the tag attached to this company
tags/name string The name of the tag attached to this company
custom_fields array An array containing information on additional fields specified for the given company
custom_fields//id int id of the additional field
custom_fields//name string Name of the additional field
custom_fields//values array An array containing information on additional fields specified for this company
custom_fields//values//value string The value of the additional field
custom_fields//values//enum string Early identifier of the preset option for the list or multi-selection
custom_fields//values//subtype string The identifier of the values ​​of the additional field "address"
custom_fields//is_system bool Is the extra systemic field
customers array An array containing information about customers who are affiliated with the company
customers/id int id of the customer attached to this company
_links array Array containing information about the request
_links/self array An array containing information about the current request
_links/self/href string Relative URL of the current request
_links/self/method string Method of the current request
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element

Response Headers contains the following headers:

  • Content-Type: application / hal + json

  • Runtime-Timestamp: 1508320306

Example response
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/companies?id=1099264",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1099264,
  12.             name: "Company LLC",
  13.             responsible_user_id: 504141,
  14.             created_by: 504141,
  15.             created_at: 1508965200,
  16.             updated_at: 1509028320,
  17.             account_id: 13667499,
  18.             updated_by: 504141,
  19.             group_id: 0,
  20.             leads: {
  21.                id: [
  22.                   1090408,
  23.                   1090409,
  24.                   1090410
  25.                ],
  26.                _links: {
  27.                   self: {
  28.                      href: "/api/v2/leads?id=1090408,1090409,1090410",
  29.                      method: "get"
  30.                  }
  31.                }
  32.             },
  33.             closest_task_at: 0,
  34.             tags: [
  35.                {
  36.                   id: 61883,
  37.                   name: "real_estate"
  38.                },
  39.                {
  40.                   id: 61884,
  41.                   name: "building"
  42.                },
  43.                {
  44.                   id: 61885,
  45.                   name: "rent"
  46.                }
  47.             ],
  48.             custom_fields: [
  49.                {
  50.                   id: 4396818,
  51.                   name: "Phone",
  52.                   values: [
  53.                      {
  54.                         value: "19999517535",
  55.                         enum: "3685087"
  56.                      },
  57.                      {
  58.                         value: "19999517535",
  59.                         enum: "3685089"
  60.                      }
  61.                   ],
  62.                   is_system: true
  63.                },
  64.                {
  65.                   id: 4396819,
  66.                   name: "Email",
  67.                   values: [
  68.                      {
  69.                         value: "company@company.moc",
  70.                         enum: "3685093"
  71.                      }
  72.                   ],
  73.                   is_system: true
  74.                },
  75.                {
  76.                   id: 4396820,
  77.                   name: "Web",
  78.                   values: [
  79.                      {
  80.                         value: http://company.moc
  81.                      }
  82.                   ],
  83.                   is_system: true
  84.                }
  85.             ],
  86.             contacts: {
  87.                id: [
  88.                   1099181,
  89.                   1099268,
  90.                   1099269
  91.                ],
  92.                _links: {
  93.                   self: {
  94.                      href: "/api/v2/contacts?id=1099181,1099268,1099269",
  95.                      method: "get"
  96.                   }
  97.                }
  98.             },
  99.             customers: [],
  100.             _links: {
  101.                self: {
  102.                   href: "/api/v2/companies?id=1099264",
  103.                   method: "get"
  104.                }
  105.             }
  106.          }
  107.       ]
  108.    }
  109. }
Example integration
  1. /* First, we need to initialize the data needed to compose the request. */
  2. $subdomain='test'; #Our account - subdomain
  3. #Generate a link for the request
  4. $link='https://'.$subdomain.'.amocrm.com/api/v2/companies';
  5. /* Note that you can pass other parameters in the reference that affect the output (see
  6. documentation).
  7. Therefore, we can replace the link given above with one of the following, or combine the parameters in the way that you want
  8. is necessary. */
  9. $link='https://'.$subdomain.'.amocrm.com/api/v2/companies';
  10. $link='https://'.$subdomain.'.amocrm.com/api/v2/companies?limit_rows=15';
  11. $link='https://'.$subdomain.'.amocrm.com/api/v2/companies?limit_rows=15&limit_offset=2';
  12. /* We need to initiate a request to the server. We use the cURL library (supplied with PHP). More about
  13. working with this
  14. library you can read in the manual. */
  15. $curl=curl_init(); #Save the cURL session descriptor
  16. #Set the necessary options for the cURL session
  17. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  18. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  19. curl_setopt($curl,CURLOPT_URL,$link);
  20. curl_setopt($curl,CURLOPT_HEADER,false);
  21. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  22. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  25. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  26. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  27. curl_close($curl);
  28. /* You can also send an additional HTTP header IF-MODIFIED-SINCE, which specifies the date in the format D, d M Y
  29. H:i:s. When
  30. Sending this header will return contacts changed later than this date. */
  31. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2013 07:07:23'));
  32. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  33. $code=(int)$code;
  34. $errors=array(
  35.   301=>'Moved permanently',
  36.   400=>'Bad request',
  37.   401=>'Unauthorized',
  38.   403=>'Forbidden',
  39.   404=>'Not found',
  40.   500=>'Internal server error',
  41.   502=>'Bad gateway',
  42.   503=>'Service unavailable'
  43. );
  44. try
  45. {
  46.   #If the response code is not 200 or 204, we return an error message
  47.  if($code!=200 && $code!=204)
  48.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  49. }
  50. catch(Exception $E)
  51. {
  52.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  53. }
  54. /*
  55.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  56.  We will have to translate the answer into a format that PHP understands
  57.  */
  58. $Response=json_decode($out,true);
  59. $Response=$Response['_embedded']['items'];