CONTACTS

One of the main essences of the system. It consists of a predefined set of fields and additional accounts created by the administrator of the account. Each contact may participate in one or more leads or may not be associated with any one at all. Each contact can be attached to one company.

E-mail contact and phone are used as unique identifiers in conjunction with other systems. For example, it is in contact that information is received about the calls made or about e-mail-correspondence.

Each contact can be assigned a responsibility to differentiate the access rights between the account's employees


Adding and updating contacts

The method allows you to add contacts one by one or in batches, as well as update data for existing contacts.

Method URL

POST/api/v2/contacts

Parameters
Parameter Type Description
add array The list of contacts to add
update array The list of existing contacts to which changes will be made. All the parameters described for add are also relevant for the update
add/name
require
string The name of the contact
add/created_at timestamp Date and time the contact was created
add/updated_at timestamp The date and time the contact was updated. Required when the entity is updated.
add/responsible_user_id int id of the user responsible for the contact
add/created_by int id of the user who created the contact
add/company_name string The name of the new company. The parameter is specified to create a new company and link the contact to it. To link a contact to an existing company, you must use the company_id parameter
add/tags string Tags that are attached to a contact. Set as a string variable, inside a line, separated by commas
add/leads_id string Leads that are tied to a contact. Listed by comma.
add/customers_id string Customers that are bound to a contact. Listed by comma.
add/company_id string Companies that are attached to a contact. Listed by comma.
add/custom_fields array An array of additional fields in the entity "Contact"
add/custom_fields//id int id of the additional field of the entity "Contact"
add/custom_fields//values array Array of values ​​of the additional field
add/custom_fields//values//value string The value of the additional field
add/custom_fields//values//enum string The early identifier of the preset choice for the list or multisession
add/custom_fields//values//subtype string The type of the element to change the additional field of the address type. Attention, all types not specified will be erased
update/id
require
int id of the contact 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 contact from other entity elements.
update/unlink/leads_id array Array id of the deals to be detached
update/unlink/company_id int id of the company to be uninstalled
update/unlink/customers_id array ID of array of detached buyers

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

Request example
  1. {
  2.       add: [
  3.          {
  4.             name: "Jason Nash",
  5.             responsible_user_id: "504141",
  6.             created_by: "504141",
  7.             created_at: "1509051600",
  8.             tags: "important, delivery",
  9.             leads_id: [
  10.                "45615",
  11.                "43510"
  12.             ],
  13.             company_id: "30615",
  14.             custom_fields: [
  15.                {
  16.                   id: "4396817",
  17.                   values: [
  18.                      {
  19.                         value: "Sales Manager"
  20.                      }
  21.                   ]
  22.                },
  23.                {
  24.                   id: "4396818",
  25.                   values: [
  26.                      {
  27.                         value: "+19990123456",
  28.                         enum: "WORK"
  29.                      },
  30.                      {
  31.                         value: "+19997894561",
  32.                         enum: "WORKDD"
  33.                      },
  34.                      {
  35.                         value: "+19991597532",
  36.                         enum: "MOB"
  37.                      }
  38.                   ]
  39.                },
  40.                {
  41.                   id: "4396819",
  42.                   values: [
  43.                      {
  44.                         value: "example@example.moc",
  45.                         enum: "WORK"
  46.                      }
  47.                   ]
  48.                },
  49.                {
  50.                   id: "4396821",
  51.                   values: [
  52.                      {
  53.                         value: "example.example",
  54.                         enum: "SKYPE"
  55.                      }
  56.                   ]
  57.                },
  58.                {
  59.                   id: "4400115",
  60.                   values: [
  61.                      {
  62.                         value: "Madison st., 1",
  63.                         subtype: "address_line_1"
  64.                      },
  65.                      {
  66.                         value: "Washington",
  67.                         subtype: "city"
  68.                      },
  69.                      {
  70.                         value: "101010",
  71.                         subtype: "zip"
  72.                      },
  73.                      {
  74.                         value: "US",
  75.                         subtype: "country"
  76.                      }
  77.                   ]
  78.                },
  79.                {
  80.                   id: "4400116",
  81.                      values: [
  82.                         "3692662",
  83.                         "3692663"
  84.                      ]
  85.                }
  86.             ]
  87.          }
  88.       ]
  89.    }

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

Request example
  1. {
  2.    update: [
  3.       {
  4.          id: "41560",
  5.          updated_at: "1508965200",
  6.          custom_fields: [
  7.             {
  8.                id: "4396819",
  9.                values: [
  10.                   {
  11.                      value: "example@example.moc",
  12.                      enum: "WORK"
  13.                   }
  14.                ]
  15.             }
  16.          ]
  17.       }
  18.    ]
  19. }
Request example
Parameter Description
id The unique identifier of the new entity
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

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

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

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

Contact list

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

Method URL

GET/api/v2/contacts/

GET parameters
Parameter Description
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
limit_rows Number of selectable rows (system limit 500)
limit_offset Shift the selection (from which row to choose). Works only if limit_rows is also specified
responsible_user_id Select the element by the responsible user (you can transfer the array with the user ID).
query Search query (Searches for the filled fields of the entity).

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 leads 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 contact ID
name string Contact name
responsible_user_id int id of the responsible user
created_by int id of the user who created the contact
created_at timestamp Date and time of creating contact
updated_at timestamp Date and time of contact change
account_id int id of the account on which the contact was created
updated_by int id of the user who updated the contact
group_id int id of the group in which the user is responsible for this contact
company array An array containing information about the company that is attached to this contact
company/id int id of the company that is attached to this contact
company/name string The name of the company that is attached to this contact
leads array An array containing information about leads that are attached to this contact
leads/id int id of the lead that is attached to this contact
closest_task_at int The nearest task for this contact
tags array An array containing information on tags attached to this contact
tags/id int id of the tag attached to this contact
tags/name string The name of the tag attached to this contact
custom_fields array An array containing information on the additional fields specified for this contact
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 the custom fields specified for this contact
custom_fields//values//value string The value of the custom field
custom_fields//values//enum string Early identifier of the preset option for the list or multisession
custom_fields//values//subtype string The identifier of the values ​​of the custom field "address"
custom_fields//is_system bool Is the extra field systemic
customers array An array containing information about customers who are attached to this contact
customers/id int id of the customer attached to this contact
_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 request
_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

Response example
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/contacts?id=1099181",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1099181,
  12.             name: "Jason Nash",
  13.             responsible_user_id: 504141,
  14.             created_by: 504141,
  15.             created_at: 1508499477,
  16.             updated_at: 1509019136,
  17.             account_id: 13667499,
  18.             updated_by: 504141,
  19.             group_id: 0,
  20.             company: {
  21.                id: 1099180,
  22.                name: "Company LLC",
  23.                _links: {
  24.                   self: {
  25.                      href: "/api/v2/companies?id=1099180",
  26.                      method: "get"
  27.                   }
  28.                }
  29.             },
  30.             leads: {
  31.                id: [
  32.                   1090391
  33.                ],
  34.                _links: {
  35.                   self: {
  36.                      href: "/api/v2/leads?id=1090391",
  37.                      method: "get"
  38.                   }
  39.                }
  40.             },
  41.             closest_task_at: 1509051540,
  42.             tags: [
  43.                {
  44.                   id: 61881,
  45.                   name: "delivery"
  46.                },
  47.                {
  48.                   id: 61882,
  49.                   name: "important"
  50.                }
  51.             ],
  52.             custom_fields: [
  53.                {
  54.                   id: 4396818,
  55.                   name: "Phone",
  56.                   values: [
  57.                      {
  58.                         value: "+19996123232",
  59.                         enum: "3685087"
  60.                      }
  61.                   ],
  62.                   is_system: true
  63.                },
  64.                {
  65.                   id: 4396821,
  66.                   name: "Instant messages",
  67.                   values: [
  68.                      {
  69.                         value: "example.example",
  70.                         enum: "3685096"
  71.                      }
  72.                   ],
  73.                   is_system: true
  74.                },
  75.                {
  76.                   id: 4400115,
  77.                   name: "Address",
  78.                   values: [
  79.                      {
  80.                         value: "Madison street, 1, Washington",
  81.                         subtype: "1"
  82.                      },
  83.                      {
  84.                         value: "US",
  85.                         subtype: "6"
  86.                      }
  87.                   ],
  88.                   is_system: false
  89.                },
  90.                {
  91.                   id: 4400116,
  92.                   name: "Multi-select",
  93.                      values: [
  94.                         {
  95.                            value: "2",
  96.                            enum: "3692663"
  97.                         },
  98.                         {
  99.                            value: "3",
  100.                            enum: "3692664"
  101.                         }
  102.                      ],
  103.                      is_system: false
  104.                }
  105.             ],
  106.             customers: {
  107.                id: [
  108.                   466791
  109.                ],
  110.                _links: {
  111.                   self: {
  112.                      href: "/api/v2/customers?id=466791",
  113.                      method: "get"
  114.                   }
  115.                }
  116.             },
  117.             _links: {
  118.                self: {
  119.                   href: "/api/v2/contacts?id=1099181",
  120.                   method: "get"
  121.                }
  122.             }
  123.          }
  124.       ]
  125.    }
  126. }
Example of integration
  1. /* First, we need to initialize the data needed to compose the query. */
  2. $subdomain='test'; #Our account - subdomain
  3. #Generate a link for the request
  4. $link='https://'.$subdomain.'.amocrm.com/api/v2/contacts/';
  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/contacts/';
  10. $link='https://'.$subdomain.'.amocrm.com/api/v2/contacts/?limit_rows=15';
  11. $link='https://'.$subdomain.'.amocrm.com/api/v2/contacts/?limit_rows=15&limit_offset=2';
  12. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  13. work with this
  14. library you can read in the manual. */
  15. $curl=curl_init(); #Save the cURL session descriptor
  16. #Set the necessary parameters 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. }
  51. catch(Exception $E)
  52. {
  53.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  54. }
  55. /*
  56.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  57.  We will have to translate the answer into a format that PHP understands
  58.  */
  59. $Response=json_decode($out,true);
  60. $Response=$Response['_embedded']['items'];
See also

ERROR CODES API