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 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 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 id, 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.

  1. {
  2.    add: [
  3.       {
  4.          name: "Pencils purchase",
  5.          created_at: "1508101200",
  6.          updated_at: "1508274000",
  7.          status_id: "13670637",
  8.          responsible_user_id: "957083",
  9.          sale: "5000",
  10.          tags: "pencil, buy",
  11.          contacts_id: [
  12.             "1099149"
  13.             ],
  14.             company_id: "1099148",
  15.             custom_fields: [
  16.                {
  17.                   id: "4399649",
  18.                   values: [
  19.                      "3691615",
  20.                      "3691616",
  21.                      "3691617"
  22.                   ]
  23.                },
  24.                {
  25.                   id: "4399656",
  26.                   values: [
  27.                      {
  28.                         value: "2017-10-26"
  29.                      }
  30.                   ]
  31.                },
  32.                {
  33.                   id: "4399655",
  34.                   values: [
  35.                      {
  36.                         value: "Madison st., 1",
  37.                         subtype: "address_line_1"
  38.                      },
  39.                      {
  40.                         value: "Washington",
  41.                         subtype: "city"
  42.                      },
  43.                      {
  44.                         value: "101010",
  45.                         subtype: "zip"
  46.                      },
  47.                      {
  48.                         value: "US",
  49.                         subtype: "country"
  50.                      }
  51.                   ]
  52.                }
  53.             ]
  54.       }
  55.    ]
  56. }
Query example

Here is an example of a request for changes in the data of an existing lead.

  1. {
  2.    update: [
  3.       {
  4.          id: "1090256",
  5.          updated_at: "1508360400",
  6.          sale: "10000",
  7.          custom_fields: [
  8.             {
  9.                id: "4399664",
  10.                values: [
  11.                   {
  12.                      value: "3691641"
  13.                   }
  14.                ]
  15.             },
  16.             {
  17.                id: "4399665",
  18.                values: [
  19.                   "3691643",
  20.                   "3691644"
  21.                ]
  22.             },
  23.             {
  24.                id: "4399663",
  25.                values: [
  26.                   {
  27.                      value: "Madison st., 2",
  28.                      subtype: "address_line_1"
  29.                   }
  30.                ]
  31.             }
  32.          ]
  33.       }
  34.    ]
  35. }
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
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/leads",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1090255,
  12.             request_id: 0,
  13.             _link: {
  14.                self: {
  15.                   href: "/api/v2/leads?id=1090255",
  16.                   method: "get"
  17.                }
  18.             }
  19.          }
  20.       ]
  21.    }
  22. }
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 describes the necessary data to create the corresponding lead.

  1. $leads['add']=array(
  2.   array(
  3.     'name'=>'Pencil Deal',
  4.     'created_at'=>1298904164,
  5.     'status_id'=>142,
  6.     'sale'=>300000,
  7.     'responsible_user_id'=>215302,
  8.     'tags' => 'Important, USA', #Tags
  9.    'custom_fields'=>array(
  10.       array(
  11.         'id'=>427496, #The unique identifier of the additional field to be populated
  12.        'values'=>array( #id values ​​are passed in the values ​​array, separated by commas
  13.            1240665,
  14.             1240664
  15.         )
  16.       ),
  17.       array(
  18.         'id'=>427497, #The unique identifier of the additional field to be populated
  19.        'values'=>array(
  20.           array(
  21.             'value'=>1240667
  22.           )
  23.         )
  24.       ),
  25.       array(
  26.         'id'=>427231, #The unique identifier of the additional field to be populated
  27.        'values'=>array(
  28.           array(
  29.             'value'=>'14.06.2014' #the delimiter is a dot
  30.          )
  31.         )
  32.       ),
  33.       array(
  34.         'id'=>458615, #The unique identifier of the additional field to be populated
  35.        'values'=>array(
  36.           array(
  37.             'value' => 'Address line 1',
  38.             'subtype' => 'address_line_1',
  39.           ),
  40.           array(
  41.             'value' => 'Address line 2',
  42.             'subtype' => 'address_line_2',
  43.           ),
  44.           array(
  45.             'value' => 'City',
  46.             'subtype' => 'city',
  47.           ),
  48.           array(
  49.             'value' => 'Region',
  50.             'subtype' => 'state',
  51.           ),
  52.           array(
  53.             'value' => '203',
  54.             'subtype' => 'zip',
  55.           ),
  56.           array(
  57.             'value' => 'US',
  58.             'subtype' => 'country',
  59.           )
  60.         )
  61.       )
  62.     )
  63.   ),
  64.   array(
  65.     'name'=>'Paper',
  66.     'created_at'=>1298904164,
  67.     'status_id'=>7087609,
  68.     'sale'=>600200,
  69.     'responsible_user_id'=>215309,
  70.     'custom_fields'=>array(
  71.       array(
  72.         #A non-standard additional field such as the "multi-list" that we created
  73.        'id'=>426106,
  74.         'values'=>array(
  75.           1237756,
  76.           1237758
  77.         )
  78.       )
  79.     )
  80.   )
  81. );
  82. /* Now prepare the data needed to query the server */
  83. $subdomain='test'; #Our account is a subdomain
  84. #Generate a link for the request
  85. $link='https://'.$subdomain.'.amocrm.com/api/v2/leads';
  86. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  87. work with this
  88. library you can read in the manual. */
  89. $curl=curl_init(); #Save the cURL session descriptor
  90. #Set the necessary parameters for the cURL session
  91. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  92. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  93. curl_setopt($curl,CURLOPT_URL,$link);
  94. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  95. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($leads));
  96. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  97. curl_setopt($curl,CURLOPT_HEADER,false);
  98. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  99. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  100. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  101. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  102. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  103. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  104. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  105. $code=(int)$code;
  106. $errors=array(
  107.   301=>'Moved permanently',
  108.   400=>'Bad request',
  109.   401=>'Unauthorized',
  110.   403=>'Forbidden',
  111.   404=>'Not found',
  112.   500=>'Internal server error',
  113.   502=>'Bad gateway',
  114.   503=>'Service unavailable'
  115. );
  116. try
  117. {
  118.   #If the response code is not 200 or 204, we return an error message
  119.  if($code!=200 && $code!=204) {
  120.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  121.   }
  122. }
  123. catch(Exception $E)
  124. {
  125.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  126. }

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_offsetShift 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 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.

  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 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
  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/leads?id=1090256",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 1090256,
  12.             name: "Lead #1090256",
  13.             responsible_user_id: 957084,
  14.             created_by: 957084,
  15.             created_at: 1508400624,
  16.             updated_at: 1508403644,
  17.             account_id: 13670640,
  18.             is_deleted: false,
  19.             main_contact: {
  20.                id: 1099418,
  21.                _links: {
  22.                   self: {
  23.                      href: "/api/v2/contacts?id=1099153",
  24.                      method: "get"
  25.                   }
  26.                }
  27.             },
  28.             group_id: 0,
  29.             company: {
  30.                id: 1099427,
  31.                name: null,
  32.                _links: {
  33.                   self: {
  34.                      href: "/api/v2/companies?id=1099152",
  35.                      method: "get"
  36.                   }
  37.                }
  38.             },
  39.             closed_at: 0,
  40.             closest_task_at: 1508446740,
  41.             tags: [],
  42.             custom_fields: [
  43.                {
  44.                   id: 4399664,
  45.                   name: "Select",
  46.                   values: [
  47.                      {
  48.                         value: "5",
  49.                         enum: "3691641"
  50.                      }
  51.                   ],
  52.                   is_system: false
  53.                },
  54.                {
  55.                   id: 4399665,
  56.                   name: "Multiselect",
  57.                   values: [
  58.                      {
  59.                         value: "2",
  60.                         enum: "3691643"
  61.                      },
  62.                      {
  63.                         value: "3",
  64.                         enum: "3691644"
  65.                      }
  66.                  ],
  67.                  is_system: false
  68.               },
  69.               {
  70.                  id: 4399666,
  71.                  name: "Text",
  72.                  values: [
  73.                     {
  74.                        value: "Notes about the lead"
  75.                     }
  76.                  ],
  77.                  is_system: false
  78.               },
  79.               {
  80.                  id: 4399663,
  81.                  name: "Address",
  82.                  values: [
  83.                     {
  84.                        value: "Madison st., 1",
  85.                        subtype: "1"
  86.                     },
  87.                     {
  88.                        value: "Washington",
  89.                        subtype: "3"
  90.                     },
  91.                     {
  92.                        value: "101010",
  93.                        subtype: "5"
  94.                     }
  95.                  ],
  96.                  is_system: false
  97.               }
  98.            ],
  99.            contacts: {
  100.               id: [
  101.                  1099418,
  102.                  1099154
  103.               ],
  104.               _links: {
  105.                  self: {
  106.                     href: "/api/v2/contacts?id=1099418,1099154",
  107.                     method: "get"
  108.                  }
  109.               }
  110.            },
  111.            status_id: 13670642,
  112.            sale: 5000,
  113.            pipeline: {
  114.               id: 10273,
  115.               _links: {
  116.                  self: {
  117.                     href: "/api/v2/pipelines?id=10246",
  118.                     method: "get"
  119.                  }
  120.               }
  121.            },
  122.            _links: {
  123.               self: {
  124.                  href: "/api/v2/leads?id=1090256",
  125.                  method: "get"
  126.               }
  127.            }
  128.         }
  129.       ]
  130.    }
  131. }
Example integration
  1. /* First, we need to initialize the data needed to compose the request. */
  2. $subdomain='test'; #Our account - subdomain
  3. /* We form the reference for the query */
  4. $link='https://'.$subdomain.'.amocrm.com/api/v2/leads';
  5. /* Note that you can pass in the reference other parameters that affect the output (see the documentation
  6. higher).
  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/leads?limit_rows=50';
  10. $link='https://'.$subdomain.'.amocrm.com/api/v2/leads?limit_rows=50&limit_offset=2';
  11. /* The following query will return a list of leads that have mail 'test@mail.com' */
  12. $link='https://'.$subdomain.'.amocrm.com/api/v2/leads?query=test@mail.com';
  13. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  14. work with this
  15. library you can read in the manual. */
  16. $curl=curl_init();
  17. /* Set the necessary parameters for the cURL session */
  18. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  19. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  20. curl_setopt($curl,CURLOPT_URL,$link);
  21. curl_setopt($curl,CURLOPT_HEADER,false);
  22. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  25. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  26. /* You can also send an additional HTTP header IF-MODIFIED-SINCE, which specifies the date in the format D, d M Y
  27. H: i: s. When
  28. The transfer of this header will be returned to leads changed later than this date. */
  29. curl_setopt($curl,CURLOPT_HTTPHEADER,array('IF-MODIFIED-SINCE: Mon, 01 Aug 2013 07:07:23'));
  30. /* We are querying the server. */
  31. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  32. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  33. curl_close($curl);
  34. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  35. $code=(int)$code;
  36. $errors=array(
  37.   301=>'Moved permanently',
  38.   400=>'Bad request',
  39.   401=>'Unauthorized',
  40.   403=>'Forbidden',
  41.   404=>'Not found',
  42.   500=>'Internal server error',
  43.   502=>'Bad gateway',
  44.   503=>'Service unavailable'
  45. );
  46. try
  47. {
  48.   /* If the response code is not 200 or 204, we return an error message */
  49.   if($code!=200 && $code!=204) {
  50.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  51.   }
  52. }
  53. catch(Exception $E)
  54. {
  55.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  56. }
  57. /*
  58.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  59.  We will have to translate the answer into a format that PHP understands
  60.  */
  61. $Response=json_decode($out,true);
  62. $Response=$Response['_embedded']['items'];
See also

ERROR CODES API