Leads
Adding and updating a lead
The method allows you to add leads one by one or in bulk, as well as update data on existing leads.
Method URL
POST/api/v2/leads
Parameters
Parameter | Type | Description |
---|---|---|
add | array | List of added deals |
update | array | Updating existing leads All the parameters that are described in add also work in the update |
add/name require |
string | Name of the lead |
add/created_at | timestamp | Date of the current lead creation |
add/updated_at | timestamp | Date of the current lead change |
add/status_id | int | Status of the lead (id of the sales phase, see Pipelines and stages of sales) To transfer the lead to another pipeline, you need to set its status from the desired pipeline |
add/pipeline_id | int | The ID of the pipeline. It is indicated if id 142 or 143 statuses are selected because These statuses are not unique and are mandatory for all digital pipelines. |
add/responsible_user_id | int | The ID of the responsible user |
add/sale | int | Deal budget |
add/tags | array/string | If you want to specify new tags, list them inside the string variable, separated by commas. If you need to attach existing tags, pass an array of numeric id values of existing tags. |
add/contacts_id | int/array | The unique identifier for the contact to contact the lead. You can pass multiple ids, listing them in an array separated by commas. |
add/company_id | int | The unique identifier of the company to contact the lead |
add/custom_fields | array | Inside this array is the contents of each filled additional field |
add/custom_fields//id | int | The unique identifier of the additional field to be populated |
add/custom_fields//values | array | Array of values |
add/custom_fields//values//value | string | The value of the additional field |
add/custom_fields//values//subtype | string | The type of the element to change the additional field of the address type. Caution, all types that were not transferred will be erased |
update/id require |
int | id of the lead to be changed |
update/updated_at required |
timestamp | Time |
update/unlink | array | An array containing information to detach a lead from other entity elements. |
update/unlink/contacts_id | array | Array id of unlinked contacts |
update/unlink/company_id | int | id of the company to be uninstalled |
Request example
Here is an example of a request to add a new lead.
{
add: [
{
name: "Pencils purchase",
created_at: "1508101200",
updated_at: "1508274000",
status_id: "13670637",
responsible_user_id: "957083",
sale: "5000",
tags: "pencil, buy",
contacts_id: [
"1099149"
],
company_id: "1099148",
custom_fields: [
{
id: "4399649",
values: [
"3691615",
"3691616",
"3691617"
]
},
{
id: "4399656",
values: [
{
value: "2017-10-26"
}
]
},
{
id: "4399655",
values: [
{
value: "Madison st., 1",
subtype: "address_line_1"
},
{
value: "Washington",
subtype: "city"
},
{
value: "101010",
subtype: "zip"
},
{
value: "US",
subtype: "country"
}
]
}
]
}
]
}
Query example
Here is an example of a request for changes in the data of an existing lead.
{
update: [
{
id: "1090256",
updated_at: "1508360400",
sale: "10000",
custom_fields: [
{
id: "4399664",
values: [
{
value: "3691641"
}
]
},
{
id: "4399665",
values: [
"3691643",
"3691644"
]
},
{
id: "4399663",
values: [
{
value: "Madison st., 2",
subtype: "address_line_1"
}
]
}
]
}
]
}
Description of response parameters
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 query |
_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
{
_links: {
self: {
href: "/api/v2/leads",
method: "post"
}
},
_embedded: {
items: [
{
id: 1090255,
request_id: 0,
_link: {
self: {
href: "/api/v2/leads?id=1090255",
method: "get"
}
}
}
]
}
}
Example of integration
To add a lead, you need to describe an array containing information about it. Our API also supports the simultaneous addition of several leads at once. To do this, we place several arrays in the query array. Each of them describes the necessary data to create the corresponding lead.
$leads['add']=array(
array(
'name'=>'Pencil Deal',
'created_at'=>1298904164,
'status_id'=>142,
'sale'=>300000,
'responsible_user_id'=>215302,
'tags' => 'Important, USA', #Tags
'custom_fields'=>array(
array(
'id'=>427496, #The unique identifier of the additional field to be populated
'values'=>array( #id values are passed in the values array, separated by commas
1240665,
1240664
)
),
array(
'id'=>427497, #The unique identifier of the additional field to be populated
'values'=>array(
array(
'value'=>1240667
)
)
),
array(
'id'=>427231, #The unique identifier of the additional field to be populated
'values'=>array(
array(
'value'=>'14.06.2014' #the delimiter is a dot
)
)
),
array(
'id'=>458615, #The unique identifier of the additional field to be populated
'values'=>array(
array(
'value' => 'Address line 1',
'subtype' => 'address_line_1',
),
array(
'value' => 'Address line 2',
'subtype' => 'address_line_2',
),
array(
'value' => 'City',
'subtype' => 'city',
),
array(
'value' => 'Region',
'subtype' => 'state',
),
array(
'value' => '203',
'subtype' => 'zip',
),
array(
'value' => 'US',
'subtype' => 'country',
)
)
)
)
),
array(
'name'=>'Paper',
'created_at'=>1298904164,
'status_id'=>7087609,
'sale'=>600200,
'responsible_user_id'=>215309,
'custom_fields'=>array(
array(
#A non-standard additional field such as the "multi-list" that we created
'id'=>426106,
'values'=>array(
1237756,
1237758
)
)
)
)
);
/* Now prepare the data needed to query the server */
$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/leads';
/* 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($leads));
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());
}
List of leads
Method for obtaining a list of leads with the possibility of filtering and pagination. Restriction on data returned on one page (offset) – 500 leads.
Method URL
GET/api/v2/leads
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 also 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 the responsible user (Can be transferred as an array) |
status | Filter by lead status ID (See here for a list of available IDs) (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 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 trade identifier |
name | string | Name of the lead |
responsible_user_id | int | id of the responsible user |
created_by | int | id of the user who created the lead |
created_at | timestamp | The time and date the lead was created |
updated_at | timestamp | Date and time of the lead change |
account_id | int | id of the account on which the lead was created |
is_deleted | bool | Deal deleted or not. Deleted leads can be in “deleted” |
main_contact | array | An array containing information about the main contact of the lead |
main_contact/id | int | id of the main contact of the lead |
group_id | int | id of the group in which the user is responsible for the lead |
company | array | An array containing information about a company that is attached to a given lead |
company/id | int | id of the company that is attached to this lead |
company/name | string | The name of the company that is attached to the lead |
closed_at | timestamp | The time and date when this lead was completed |
closest_task_at | timestamp | The time of the nearest task for this lead |
tags | array | An array containing information on tags attached to a given lead |
tags/id | int | id of the tag attached to this trade |
tags/name | string | The name of the tag attached to this lead |
custom_fields | array | An array containing information on the additional fields specified for this lead |
custom_fields//id | int | id of the custom field |
custom_fields//name | string | name of the custom field |
custom_fields//values | array | An array containing information on the custom fields specified for this lead |
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 additional field “address” |
custom_fields//is_system | bool | Is the extra field systemic |
contacts | array | An array containing information on contacts attached to a given lead |
contacts/id | int | id of the contact attached to the lead |
status_id | int | id of the digital pipeline segment on which the lead is located |
sale | int | Budget of the lead |
pipeline | array | An array containing information on the digital pipeline in which the lead is located |
pipeline/id | int | id of the digital pipeline in which the lead is located |
_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
Response example
{
_links: {
self: {
href: "/api/v2/leads?id=1090256",
method: "get"
}
},
_embedded: {
items: [
{
id: 1090256,
name: "Lead #1090256",
responsible_user_id: 957084,
created_by: 957084,
created_at: 1508400624,
updated_at: 1508403644,
account_id: 13670640,
is_deleted: false,
main_contact: {
id: 1099418,
_links: {
self: {
href: "/api/v2/contacts?id=1099153",
method: "get"
}
}
},
group_id: 0,
company: {
id: 1099427,
name: null,
_links: {
self: {
href: "/api/v2/companies?id=1099152",
method: "get"
}
}
},
closed_at: 0,
closest_task_at: 1508446740,
tags: [],
custom_fields: [
{
id: 4399664,
name: "Select",
values: [
{
value: "5",
enum: "3691641"
}
],
is_system: false
},
{
id: 4399665,
name: "Multiselect",
values: [
{
value: "2",
enum: "3691643"
},
{
value: "3",
enum: "3691644"
}
],
is_system: false
},
{
id: 4399666,
name: "Text",
values: [
{
value: "Notes about the lead"
}
],
is_system: false
},
{
id: 4399663,
name: "Address",
values: [
{
value: "Madison st., 1",
subtype: "1"
},
{
value: "Washington",
subtype: "3"
},
{
value: "101010",
subtype: "5"
}
],
is_system: false
}
],
contacts: {
id: [
1099418,
1099154
],
_links: {
self: {
href: "/api/v2/contacts?id=1099418,1099154",
method: "get"
}
}
},
status_id: 13670642,
sale: 5000,
pipeline: {
id: 10273,
_links: {
self: {
href: "/api/v2/pipelines?id=10246",
method: "get"
}
}
},
_links: {
self: {
href: "/api/v2/leads?id=1090256",
method: "get"
}
}
}
]
}
}
Example integration
/* First, we need to initialize the data needed to compose the request. */
$subdomain='test'; #Our account - subdomain
/* We form the reference for the query */
$link='https://'.$subdomain.'.amocrm.com/api/v2/leads';
/* Note that you can pass in the reference other parameters that affect the output (see the documentation higher).
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/leads?limit_rows=50';
$link='https://'.$subdomain.'.amocrm.com/api/v2/leads?limit_rows=50&limit_offset=2';
/* The following query will return a list of leads that have mail 'test@mail.com' */
$link='https://'.$subdomain.'.amocrm.com/api/v2/leads?query=test@mail.com';
/* 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();
/* 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);
/* 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
The transfer of this header will be returned to leads changed later than this date. */
curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2013 07:07:23'));
/* We are querying the server. */
$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);
/* 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