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
{
add: [
{
name: "Company LLC",
responsible_user_id: "504141",
created_by: "504141",
created_at: "1509051600",
tags: "real_estate, development, rent",
leads_id: [
"45615",
"43510"
],
custom_fields: [
{
id: "4396817",
values: [
{
value: "5"
}
]
},
{
id: "4396818",
values: [
{
value: "19999517535",
enum: "WORK"
},
{
value: "19991237895",
enum: "MOB"
}
]
},
{
id: "4396819",
values: [
{
value: "company@company.moc",
enum: "WORK"
}
]
},
{
id: "4396820",
values: [
{
value: "company.moc"
}
]
},
{
id: "4400115",
values: [
{
value: "Madison st, 2",
subtype: "address_line_1"
},
{
value: "Washington",
subtype: "city"
},
{
value: "20011",
subtype: "zip"
},
{
value: "US",
subtype: "country"
}
]
}
]
}
]
}
Here is an example of a request to update a company.
Example request
{
update: [
{
id: "41389",
updated_at: "1508965200",
custom_fields: [
{
id: "315289",
values: [
{
value: "example.moc",
enum: "WEB"
}
]
}
]
}
]
}
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
{
_links: {
self: {
href: "/api/v2/companies",
method: "post"
}
},
_embedded: {
items: [
{
id: 1099264,
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
}
}
]
}
}
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.
$companies['add']=array(
array(
'name' => ''Company LLC'',
'responsible_user_id' => 504141,
'created_by' => 504141,
'created_at' => "1509051600",
'tags' => "real_estate, development, rent",
'leads_id' => array(
"45615",
"43510"
),
'custom_fields' => array(
array(
'id' => 4396818,
'values' => array(
array(
'value' => "19999517535",
'enum' => "WORK"
),
array(
'value' => "19991237895",
'enum' => "MOB"
)
)
),
array(
'id' => 4396819,
'values' => array(
array(
'value' => "company@company.moc",
'enum' => "WORK"
)
)
),
array(
'id' => 4400115,
'values' => array(
array(
'value' => "Madison st., 2",
'subtype' => "address_line_1"
),
array(
value: "Washington",
subtype: "city"
),
array(
value: "20011",
subtype: "zip"
),
array(
value: "US",
subtype: "country"
)
)
),
array(
'id' => 3789654,
'values' => array(
"2615948",
"2648159",
"2653867"
)
)
)
)
)
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account - a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/companies';
/* We need to initiate a request to the server. We use the cURL library (supplied as PHP). More about working with this library you can read in the manual.*/
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary options 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($companies));
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); #Initialize 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());
}
/*
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'];
$output=''The ID of the added contacts:'.PHP_EOL;
foreach($Response as $v)
if(is_array($v))
$output.=$v['id'].PHP_EOL;
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_offset | Shift 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.
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
{
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
},
_embedded: {
items: [
{
id: 1099264,
name: "Company LLC",
responsible_user_id: 504141,
created_by: 504141,
created_at: 1508965200,
updated_at: 1509028320,
account_id: 13667499,
updated_by: 504141,
group_id: 0,
leads: {
id: [
1090408,
1090409,
1090410
],
_links: {
self: {
href: "/api/v2/leads?id=1090408,1090409,1090410",
method: "get"
}
}
},
closest_task_at: 0,
tags: [
{
id: 61883,
name: "real_estate"
},
{
id: 61884,
name: "building"
},
{
id: 61885,
name: "rent"
}
],
custom_fields: [
{
id: 4396818,
name: "Phone",
values: [
{
value: "19999517535",
enum: "3685087"
},
{
value: "19999517535",
enum: "3685089"
}
],
is_system: true
},
{
id: 4396819,
name: "Email",
values: [
{
value: "company@company.moc",
enum: "3685093"
}
],
is_system: true
},
{
id: 4396820,
name: "Web",
values: [
{
value: http://company.moc
}
],
is_system: true
}
],
contacts: {
id: [
1099181,
1099268,
1099269
],
_links: {
self: {
href: "/api/v2/contacts?id=1099181,1099268,1099269",
method: "get"
}
}
},
customers: [],
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
}
}
]
}
}
Example integration
/* First, we need to initialize the data needed to compose the request. */
$subdomain='test'; #Our account - subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/companies';
/* 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/companies';
$link='https://'.$subdomain.'.amocrm.com/api/v2/companies?limit_rows=15';
$link='https://'.$subdomain.'.amocrm.com/api/v2/companies?limit_rows=15&limit_offset=2';
/* We need to initiate a request to the server. We use the cURL library (supplied with PHP). More about working with this library you can read in the manual.*/
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary options 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'];