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 anyone 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 a comma. |
add/customers_id | string | Customers that are bound to a contact. Listed by a comma. |
add/company_id | string | Companies that are attached to a contact. Listed by a 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 | The 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 | The ID of the array of detached buyers |
Here is an example of a request to add a new contact.
Request example
{
add: [
{
name: "Jason Nash",
responsible_user_id: "504141",
created_by: "504141",
created_at: "1509051600",
tags: "important, delivery",
leads_id: [
"45615",
"43510"
],
company_id: "30615",
custom_fields: [
{
id: "4396817",
values: [
{
value: "Sales Manager"
}
]
},
{
id: "4396818",
values: [
{
value: "+19990123456",
enum: "WORK"
},
{
value: "+19997894561",
enum: "WORKDD"
},
{
value: "+19991597532",
enum: "MOB"
}
]
},
{
id: "4396819",
values: [
{
value: "example@example.moc",
enum: "WORK"
}
]
},
{
id: "4396821",
values: [
{
value: "example.example",
enum: "SKYPE"
}
]
},
{
id: "4400115",
values: [
{
value: "Madison st., 1",
subtype: "address_line_1"
},
{
value: "Washington",
subtype: "city"
},
{
value: "101010",
subtype: "zip"
},
{
value: "US",
subtype: "country"
}
]
},
{
id: "4400116",
values: [
"3692662",
"3692663"
]
}
]
}
]
}
Here is an example of a request to update a contact.
Request example
{
update: [
{
id: "41560",
updated_at: "1508965200",
custom_fields: [
{
id: "4396819",
values: [
{
value: "example@example.moc",
enum: "WORK"
}
]
}
]
}
]
}
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 | An 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
{
_link: {
self: {
href: "/api/v2/contacts",
method: "post"
}
},
_embedded: {
items: [
{
id: 1099235,
_link: {
self: {
href: "/api/v2/contacts?id=1099235",
method: "get"
}
}
}
]
}
}
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.
$contacts['add']=array(
array(
'name' => 'Jason Nash',
'responsible_user_id' => 504141,
'created_by' => 504141,
'created_at' => "1509051600",
'tags' => "important, delivery",
'leads_id' => array(
"45615",
"43510"
),
'company_id' => 30615,
'custom_fields' => array(
array(
'id' => 4396817,
'values' => array(
array(
'value' => "Sales Manager"
)
)
),
array(
'id' => 4396818,
'values' => array(
array(
'value' => "+19990123456",
'enum' => "WORK"
),
array(
'value' => "+19997894561",
'enum' => "WORKDD"
),
array(
'value' => "+19991597532",
'enum' => "MOB"
)
)
),
array(
'id' => 4396819,
'values' => array(
array(
'value' => "example@example.moc",
'enum' => "WORK"
)
)
),
array(
'id' => 4396821,
'values' => array(
array(
'value' => "example.example",
'enum' => "SKYPE"
)
)
),
array(
'id' => 4400115,
'values' => array(
array(
'value' => "Madison street, 1",
'subtype' => "address_line_1"
),
array(
value: "Washington",
subtype: "city"
),
array(
value: "101010",
subtype: "zip"
),
array(
value: "US",
subtype: "country"
)
)
),
array(
'id' => 4400116,
'values' => array(
"3692662",
"3692663"
)
)
)
)
)
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account - subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/contacts';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary parameters for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($contacts));
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type:application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
301=>'Moved permanently',
400=>'Bad request',
401=>'Unauthorized',
403=>'Forbidden',
404=>'Not found',
500=>'Internal server error',
502=>'Bad gateway',
503=>'Service unavailable'
);
try
{
#If the response code is not 200 or 204, we return an error message
if($code!=200 && $code!=204) {
throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
}
catch(Exception $E)
{
die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}
/*
he data is obtained in the JSON format, therefore, in order to obtain readable data,
We will have to translate the answer into a format that PHP understands
*/
$Response=json_decode($out,true);
$Response=$Response[_embedded']['items'];
$output='The ID of the added contacts:'.PHP_EOL;
foreach($Response as $v)
if(is_array($v))
$output.=$v['id'].PHP_EOL;
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.
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 | An 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
{
_links: {
self: {
href: "/api/v2/contacts?id=1099181",
method: "get"
}
},
_embedded: {
items: [
{
id: 1099181,
name: "Jason Nash",
responsible_user_id: 504141,
created_by: 504141,
created_at: 1508499477,
updated_at: 1509019136,
account_id: 13667499,
updated_by: 504141,
group_id: 0,
company: {
id: 1099180,
name: "Company LLC",
_links: {
self: {
href: "/api/v2/companies?id=1099180",
method: "get"
}
}
},
leads: {
id: [
1090391
],
_links: {
self: {
href: "/api/v2/leads?id=1090391",
method: "get"
}
}
},
closest_task_at: 1509051540,
tags: [
{
id: 61881,
name: "delivery"
},
{
id: 61882,
name: "important"
}
],
custom_fields: [
{
id: 4396818,
name: "Phone",
values: [
{
value: "+19996123232",
enum: "3685087"
}
],
is_system: true
},
{
id: 4396821,
name: "Instant messages",
values: [
{
value: "example.example",
enum: "3685096"
}
],
is_system: true
},
{
id: 4400115,
name: "Address",
values: [
{
value: "Madison street, 1, Washington",
subtype: "1"
},
{
value: "US",
subtype: "6"
}
],
is_system: false
},
{
id: 4400116,
name: "Multi-select",
values: [
{
value: "2",
enum: "3692663"
},
{
value: "3",
enum: "3692664"
}
],
is_system: false
}
],
customers: {
id: [
466791
],
_links: {
self: {
href: "/api/v2/customers?id=466791",
method: "get"
}
}
},
_links: {
self: {
href: "/api/v2/contacts?id=1099181",
method: "get"
}
}
}
]
}
}
Example of integration
/* First, we need to initialize the data needed to compose the query. */
$subdomain='test'; #Our account - subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/contacts/';
/* Note that you can pass other parameters in the reference that affect the output (see documentation).
Therefore, we can replace the link given above with one of the following, or combine the parameters in the way that you want is necessary. */
$link='https://'.$subdomain.'.amocrm.com/api/v2/contacts/';
$link='https://'.$subdomain.'.amocrm.com/api/v2/contacts/?limit_rows=15';
$link='https://'.$subdomain.'.amocrm.com/api/v2/contacts/?limit_rows=15&limit_offset=2';
/* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary parameters for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
curl_close($curl);
/* You can also send an additional HTTP header IF-MODIFIED-SINCE, which specifies the date in the format D, d M Y
H: i: s. When
Sending this header will return contacts changed later than this date. */
curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2013 07:07:23'));
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
301=>'Moved permanently',
400=>'Bad request',
401=>'Unauthorized',
403=>'Forbidden',
404=>'Not found',
500=>'Internal server error',
502=>'Bad gateway',
503=>'Service unavailable'
);
try
{
#If the response code is not 200 or 204, we return an error message
if($code!=200 && $code!=204) {
throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
}
catch(Exception $E)
{
die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}
/*
The data is obtained in the JSON format, therefore, in order to obtain readable data,
We will have to translate the answer into a format that PHP understands
*/
$Response=json_decode($out,true);
$Response=$Response['_embedded']['items'];
See also