INCOMING LEADS

The state of the Incoming leads includes all calls from integrations: telephony and forms for the site that have not yet been processed by the user (a lead or contact has been created). The user can accept the Incoming lead, or reject it. If accepted, a lead will be created, as well as a contact and / or company, if the relevant information is in the request. If the request is rejected, the data will be deleted.


Adding to the Incoming Leads

The method allows you to add unparsed one by one or batch.

Common parameters
Parameter Type Description
add/source_name
require
string Name of the source of the request
add/source_uid
require
string Unique request identifier
add/pipeline_id int Pipeline ID, if the parameter is not passed, then the request will be added to the unshaped primary pipeline
add/incoming_lead_info array An array containing information about the received
add/incoming_entities
require
array An array containing information about the created entity elements. It is mandatory, because after the adparameter of the unseparated, the corresponding elements of the entity will be created.
add/incoming_entities/leads array An array containing information for creating a new lead. Can contain all the parameters and Custom fieldss available for leads for the current account.
add/incoming_entities/contacts array An array containing information for creating a new contact. Can contain all the parameters and Custom fieldss available for contacts for the current account.
add/incoming_entities/companies array An array containing information for creating a new company. Can contain all the parameters and Custom fieldss available to companies for the current account.

A new request in the incoming leads can be one of the available types:

  • Incoming call (sip)

  • Web Form

Add an request from an incoming call:

Method URL

POST / api / v2 / incoming_leads / sip

Parameters for sip
Parameter Type Description
add/incoming_lead_info/to
require
int ID of the user who received the call
add/incoming_lead_info/from
require
string External phone number from which the call was received
add/incoming_lead_info/date_call
require
timestamp Date and time of call
add/incoming_lead_info/duration
require
int Call duration
add/incoming_lead_info/link
require
string Link to record a call
add/incoming_lead_info/service_code
require
string The code of the widget or service through which the call was made
add/incoming_lead_info/uniq
require
string Unique call code
add/incoming_lead_info/add_note
require
bool Flag, if this parameter is passed, then after the acceptance of the request in the created entities an event about the made call will be added.
Response example
  1. {
  2.    add: [
  3.       {
  4.          source_name: "EcoSport",
  5.          source_uid: "a1fee7c0fc436088e64ba2e8822ba2b3",
  6.          created_at: "1510261200",
  7.          pipeline_id: "41563",
  8.          incoming_entities: {
  9.             leads: [
  10.                {
  11.                   name: "Maintenance of chain saws",
  12.                   created_at: "1509483600",
  13.                   status_id: "13667502",
  14.                   responsible_user_id: "504141",
  15.                   price: "1000",
  16.                   tags: "MT, services",
  17.                   notes: [
  18.                      {
  19.                         note_type: "7",
  20.                         element_type: "lead",
  21.                         text: "Send a duplicate of the contract"
  22.                      }
  23.                   ],
  24.                   custom_fields: [
  25.                      {
  26.                         id: "4399917",
  27.                         values: [
  28.                            "3692247",
  29.                            "3692248"
  30.                         ]
  31.                      }
  32.                   ]
  33.                }
  34.             ],
  35.             contacts: [
  36.                {
  37.                   name: "Jason Nash",
  38.                   custom_fields: [
  39.                      {
  40.                         id: "4396818",
  41.                         values: [
  42.                            {
  43.                               value: "+19457898713",
  44.                               enum: "WORK"
  45.                            }
  46.                         ]
  47.                      },
  48.                      {
  49.                         id: "4396819",
  50.                         values: [
  51.                            {
  52.                               value: "email@email.com",
  53.                               enum: "WORK"
  54.                            }
  55.                         ]
  56.                      },
  57.                      {
  58.                         id: "4400115",
  59.                         values: [
  60.                            {
  61.                               value: "Madison street, 1",
  62.                               subtype: "address_line_1"
  63.                            },
  64.                            {
  65.                               value: "Washington",
  66.                               subtype: "city"
  67.                            },
  68.                            {
  69.                               value: "20011",
  70.                               subtype: "zip"
  71.                            },
  72.                            {
  73.                               value: "US",
  74.                               subtype: "country"
  75.                            }
  76.                         ]
  77.                      }
  78.                   ],
  79.                   responsible_user_id: "504141",
  80.                   date_create: "1509483600"
  81.                }
  82.             ],
  83.             companies: [
  84.                {
  85.                   name: "EcoSport"
  86.                }
  87.             ]
  88.          },
  89.          incoming_lead_info: {
  90.             to: "41565",
  91.             from: "+19456153101",
  92.             date_call: "1509483600",
  93.             duration: "54",
  94.             link: "https://www.example.com/records/2017/11/01/98431.mp3",
  95.             service_code: "CkKwPam6",
  96.             uniq: "a1fee7c0fc436088e64ba2e8822ba2b3ewrw",
  97.             add_note: "We agreed on cooperation"
  98.          }
  99.       }
  100.    ]
  101. }

In the preview of the request card (received through the web form), information received from the entity arrays (add / incoming_entities) is displayed in the incoming leads. In this case, it is necessary to take into account the existing priority of obtaining information from these arrays by type of entity.

Priority of entity types, for displaying information in the request form:

  1. Contact

  2. Lead

  3. Customer

To display in the request form, the following information is taken.

  • Entity element name

  • Tags

  • Custom fieldss and their meanings

Adding an request from the web form:

Method URL

POST / api / v2 / incoming_leads / form

Parameters for the web form:
Parameter Type Description
add/incoming_lead_info/form_id
require
int Form identifier
add/incoming_lead_info/form_page
require
string The address of the page on which the form is located
add/incoming_lead_info/ip
require
string IP address from which the request was received
add/incoming_lead_info/service_code
require
string Widget or service code
add/incoming_lead_info/form_name string Form name
add/incoming_lead_info/form_send_at timestamp Date and time of sending data via form
add/incoming_lead_info/referer string The parameter contains information from where to go to the page where the form is located.
Response example
  1. {
  2.    add: [
  3.       {
  4.          source_name: "Company LLC",
  5.          source_uid: "a1fee7c0fc436088e64ba2e8822ba2b3",
  6.          pipeline_id: "41563",
  7.          incoming_entities: {
  8.             leads: [
  9.                {
  10.                   name: "Maintenance of rotary hammers",
  11.                   created_at: "1509483600",
  12.                   status_id: "13667502",
  13.                   responsible_user_id: "504141",
  14.                   sale: "45000",
  15.                   tags: "MT, services",
  16.                   notes: [
  17.                      {
  18.                         note_type: "7",
  19.                         element_type: "lead",
  20.                         text: "Send an invoice"
  21.                      }
  22.                   ],
  23.                   custom_fields: [
  24.                      {
  25.                         id: "4399917",
  26.                         values: [
  27.                            "3692247",
  28.                            "3692248"
  29.                         ]
  30.                      }
  31.                   ]
  32.                }
  33.             ],
  34.             contacts: [
  35.                {
  36.                   name: "Jeremy Paul",
  37.                   custom_fields: [
  38.                      {
  39.                         id: "4396818",
  40.                         values: [
  41.                            {
  42.                               value: "+19451456510",
  43.                               enum: "WORK"
  44.                            }
  45.                         ]
  46.                      },
  47.                      {
  48.                         id: "4396819",
  49.                         values: [
  50.                            {
  51.                               value: "email@email.com",
  52.                               enum: "WORK"
  53.                            }
  54.                         ]
  55.                      },
  56.                      {
  57.                         id: "4400115",
  58.                         values: [
  59.                            {
  60.                               value: "Madison street, 1",
  61.                               subtype: "address_line_1"
  62.                            },
  63.                            {
  64.                               value: "Washington",
  65.                               subtype: "city"
  66.                            },
  67.                            {
  68.                               value: "20011",
  69.                               subtype: "zip"
  70.                            },
  71.                            {
  72.                               value: "US",
  73.                               subtype: "country"
  74.                            }
  75.                         ]
  76.                      }
  77.                   ],
  78.                   responsible_user_id: "504141",
  79.                   created_at: "1509483600"
  80.                }
  81.             ],
  82.             companies: [
  83.                {
  84.                   name: "Company LLC"
  85.                }
  86.             ]
  87.          },
  88.          incoming_lead_info: {
  89.             form_id: "159783",
  90.             form_page: "example.com",
  91.             ip: "127.0.0.1",
  92.             service_code: "QkKwSam8",
  93.             form_name: "Leave a request",
  94.             form_send_at: "1509483600",
  95.             referer: http://example.com/index.php?ref=103719
  96.          }
  97.       }
  98.    ]
  99. }
Response parameters
Parameter Type Description
status string Adding status: success or fail
data array An array containing the unique identifiers of the added orders in the Incoming Leads
_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
error string Description of the cause of the error. Transmitted only when an error occurs.
error_code int Error code
Response parameters
  1. {
  2.    status: "success",
  3.    data: {
  4.       "561a8a8b7d7a8cbc440965903605a27685a9ec37317bc395636a481e31f7"
  5.    },
  6.    _links: {
  7.       self: {
  8.          href: "/api/v2/incoming_leads/form?login=example@example.com&api_key=24db154826a13a988893be1da61",
  9.          method: "post"
  10.       }
  11.    }
  12. }
Example integration
  1. /* First, we need to initialize the data needed to compose the query. */
  2. $data = array (
  3.   'add' =>
  4.   array (
  5.     0 =>
  6.     array (
  7.       'source_name' => 'Company LLC',
  8.       'source_uid' => 'a1fee7c0fc436088e64ba2e8822ba2b3',
  9.       'pipeline_id' => '41563',
  10.       'created_at' => '1509483600',
  11.       'incoming_entities' =>
  12.       array (
  13.         'leads' =>
  14.         array (
  15.           0 =>
  16.           array (
  17.             'name' => 'Maintenance of the chainsaw',
  18.             'created_at' => '1509483600',
  19.             'status_id' => '13667502',
  20.             'responsible_user_id' => '504141',
  21.             'price' => '1000',
  22.             'tags' => 'MT, services'',
  23.             'custom_fields' =>
  24.             array (
  25.               0 =>
  26.               array (
  27.                 'id' => '4399917',
  28.                 'values' =>
  29.                 array (
  30.                   0 => '3692247',
  31.                   1 => '3692248',
  32.                 ),
  33.               ),
  34.               1 =>
  35.               array (
  36.                 'id' => '4399923',
  37.                 'values' =>
  38.                 array (
  39.                   0 =>
  40.                   array (
  41.                     'value' => 'Madison st. 1',
  42.                     'subtype' => 'address_line_1',
  43.                   ),
  44.                   1 =>
  45.                   array (
  46.                     'value' => 'Washington',
  47.                     'subtype' => 'city',
  48.                   ),
  49.                   2 =>
  50.                   array (
  51.                     'value' => '20011',
  52.                     'subtype' => 'zip',
  53.                   ),
  54.                   3 =>
  55.                   array (
  56.                     'value' => 'US',
  57.                     'subtype' => 'country',
  58.                   ),
  59.                 ),
  60.               ),
  61.             ),
  62.           ),
  63.         ),
  64.         'contacts' =>
  65.         array (
  66.           0 =>
  67.           array (
  68.             'name' => 'Jason Nash',
  69.             'custom_fields' =>
  70.             array (
  71.               0 =>
  72.               array (
  73.                 'id' => '4396818',
  74.                 'values' =>
  75.                 array (
  76.                   0 =>
  77.                   array (
  78.                     'value' => '+19457898713',
  79.                     'enum' => 'WORK',
  80.                   ),
  81.                 ),
  82.               ),
  83.               1 =>
  84.               array (
  85.                 'id' => '4396819',
  86.                 'values' =>
  87.                 array (
  88.                   0 =>
  89.                   array (
  90.                     'value' => 'email@email.com',
  91.                     'enum' => 'WORK',
  92.                   ),
  93.                 ),
  94.               ),
  95.             ),
  96.             'responsible_user_id' => '504141',
  97.           ),
  98.         ),
  99.         'companies' =>
  100.         array (
  101.           0 =>
  102.           array (
  103.             'name' => 'Company LLC',
  104.           ),
  105.         ),
  106.       ),
  107.       'incoming_lead_info' =>
  108.       array (
  109.         'to' => '41565',
  110.         'from' => '+19456153101',
  111.         'date_call' => '1509483600',
  112.         'duration' => '56',
  113.         'link' => 'https://www.example.com/records/2017/11/01/98431.mp3',
  114.         'service_code' => 'CkKwPam6',
  115.         'uniq' => 'a1fee7c0fc436088e64ba2e8822ba2b3ewrw',
  116.         'add_note' => 'Send a duplicate of the contract',
  117.       ),
  118.     ),
  119.   ),
  120. );
  121. $subdomain='test'; #Our account is a subdomain
  122. #Generate a link for the request
  123. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads/sip';
  124. /* Note that you can pass other parameters in the reference that affect the output (see
  125. documentation).
  126. Therefore, we can replace the link given above with one of the following, or combine the parameters in the way
  127. that you want. */
  128. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads/sip?api_key='.$api_key.'&login='.$login;
  129. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  130. work with this
  131. library you can read in the manual. */
  132. $curl=curl_init(); #Save the cURL session descriptor
  133. #Set the necessary parameters for the cURL session
  134. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  135. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  136. curl_setopt($curl,CURLOPT_HTTPHEADER,['Accept: application/json']);
  137. curl_setopt($curl,CURLOPT_URL,$link);
  138. curl_setopt($curl,CURLOPT_HEADER,false);
  139. curl_setopt($curl,CURLOPT_POSTFIELDS, http_build_query($data));
  140. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  141. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  142. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  143. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  144. curl_close($curl);
  145. /*Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  146. $code=(int)$code;
  147. $errors=array(
  148.   301=>'Moved permanently',
  149.   400=>'Bad request',
  150.   401=>'Unauthorized',
  151.   403=>'Forbidden',
  152.   404=>'Not found',
  153.   500=>'Internal server error',
  154.   502=>'Bad gateway',
  155.   503=>'Service unavailable'
  156. );
  157. try
  158. {
  159.   #If the response code is not 200, 201 or 204, we return an error message
  160.  if(!in_array($code, [200, 201, 204]))
  161.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  162. }
  163. catch(Exception $E)
  164. {
  165.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  166. }
  167. /*
  168.  The data is obtained in the JSON format, therefore, in order to obtain readable data,
  169.  We will have to translate the response into a format that PHP understands
  170.  */
  171. $Response=json_decode($out,true);
  172. $Response=$Response['data'];

Acceptance of incoming leads

Method for accepting incoming requests.

Method URL

POST / api / v2 / incoming_leads / accept

Parameters
Parameter Type Description
accept array(string) An array of unique identifiers (uid) of unsorted orders
user_id int id of the account user, on behalf of which leads / contacts / companies will be created
status_id int The status of leads that will be created as a result of the adoption of an Incoming lead
Response example
  1. {
  2.    accept: [
  3.       "6d054b50e0769b0d8bdaed73901e6a544ba329aa1d0d2f0d25fde025398e",
  4.       "56df4sg6dfs5g1f56bdaed65498e6asd56f4ds65f4SDds6f54sd65f4d89q"
  5.    ],
  6.    user_id: "504141",
  7.    status_id: "142"
  8. }
Response parameters
Parameter Type Description
status string Adding status: success or fail
data array An array containing the unique identifiers of the added orders in the Incoming Leads
data//companies array An array containing the id of the created company
data//leads array An array containing the id of the created leads
data//contacts array An array containing the id of the created contacts
_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
error string Description of the cause of the error. Transmitted only when an error occurs.

Response Headers contains the following headers:

  • Content-Type:application/hal+json

  • Runtime-Timestamp: 1508320306

Response example
  1. {
  2.    status: "success",
  3.    data: {
  4.       561a8a8b7d7a8cbc440965903605a27685a9ec37317bc395636a481e31f7: {
  5.          companies: [
  6.             1099388
  7.          ],
  8.          leads: [
  9.             1090596
  10.          ],
  11.          contacts: [
  12.             1099389
  13.          ]
  14.       }
  15.    },
  16.    _links: {
  17.       self: {
  18.          href: "/api/v2/incoming_leads/accept?login=dhnikolas2@gmail.com&api_key=24dbfd65b23ff2ea13a988893be1da61",
  19.          method: "post"
  20.       }
  21.    }
  22. }

To accept an unparsed, it is necessary to describe an array containing request identifiers. Also, you must specify the user id as an element of the $data array. You can specify the status of the resulting lead.

Example integration:
  1. $data=array(
  2.   'accept' => array(
  3.     '6d054b50e0769b0d8bdaed73901e6a544ba329aa1d0d2f0d25fde025398e',
  4.     '56df4sg6dfs5g1f56bdaed65498e6asd56f4ds65f4SDds6f54sd65f4d89q'
  5.   ),
  6.   'user_id' => 102525,
  7.   'status_id' => 1023486
  8. );
  9. $subdomain='test'; #Our account is a subdomain
  10. #Generate a link for the request
  11. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads/accept/';
  12. /* Note that you can pass other parameters in the reference that affect the output (see
  13. documentation).
  14. Therefore, we can replace the link given above with one of the following, or combine the parameters
  15. in the way that you want. */
  16. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads/accept?api_key='.$api_key.'&login='.$login;
  17. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  18. work with this
  19. library you can read in the manual. */
  20. $curl=curl_init(); #Save the cURL session descriptor
  21. #Set the necessary parameters for the cURL session
  22. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  23. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  24. curl_setopt($curl,CURLOPT_HTTPHEADER,['Accept: application/json']);
  25. curl_setopt($curl,CURLOPT_URL,$link);
  26. curl_setopt($curl,CURLOPT_HEADER,false);
  27. curl_setopt($curl,CURLOPT_POSTFIELDS, http_build_query($data));
  28. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  29. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  30. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  31. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  32. curl_close($curl);
  33. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  34. $code=(int)$code;
  35. $errors=array(
  36.   301=>'Moved permanently',
  37.   400=>'Bad request',
  38.   401=>'Unauthorized',
  39.   403=>'Forbidden',
  40.   404=>'Not found',
  41.   500=>'Internal server error',
  42.   502=>'Bad gateway',
  43.   503=>'Service unavailable'
  44. );
  45. try
  46. {
  47.   #If the response code is not 200, 201 or 204, we return an error message
  48.  if(!in_array($code, [200, 201, 204])
  49.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  50. }
  51. catch(Exception $E)
  52. {
  53.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  54. }

Declining of incoming leads

Method for rejecting unlisted requests.

Method URL

POST / api / v2 / incoming_leads / decline

Parameters
Parameter Type Description
decline array Array of unique identifiers (uid) of unsorted orders
user_id int id of the user on whose behalf the request will be rejected
Response example
  1. {
  2.    decline: [
  3.       "6d054b50e0769b0d8bdaed73901e6a544ba329aa1d0d2f0d25fde025398e",
  4.       "56df4sg6dfs5g1f56bdaed65498e6asd56f4ds65f4SDds6f54sd65f4d89q"
  5.    ],
  6.    user_id: "504141"
  7. }
Response parameters:
Parameter Type Description
status string Adding status: success or fail
data array An array containing unique request identifiers in the Incoming Leads
_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
error string Description of the cause of the error. Transmitted only when an error occurs.

Response Headers contains the following headers:

  • Content-Type:application/hal+json

  • Runtime-Timestamp: 1508320306

Response example
  1. {
  2.    status: "success",
  3.       data: {
  4.          86c4ff85844722b75fcd0bed7b6fe0ac099a3a1e20e70823dcd634fc8e69: false
  5.       },
  6.       _links: {
  7.          self: {
  8.             href: "/api/v2/incoming_leads/decline?login=example@example.com&api_key=7d4cebf7b176a2c3dc84b365eea7e1260af",
  9.             method: "post"
  10.          }
  11.       }
  12. }

To reject an unparsed, it is necessary to describe an array containing the identifiers of the claims. You must also specify the user id.

Example integration
  1. $data=array(
  2.   'decline' => array(
  3.     '6d054b50e0769b0d8bdaed73901e6a544ba329aa1d0d2f0d25fde025398e',
  4.     '56df4sg6dfs5g1f56bdaed65498e6asd56f4ds65f4SDds6f54sd65f4d89q'
  5.   ),
  6.   'user_id' => 102525
  7. );
  8. $subdomain='test'; #Our account is a subdomain
  9. #Generate a link for the request
  10. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads/decline';
  11. /* Note that you can pass other parameters in the reference that affect the output (see
  12. documentation).
  13. Therefore, we can replace the link given above with one of the following, or combine the parameters
  14. in the way that you want. */
  15. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads/decline?api_key='.$api_key.'&login='.$login;
  16. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  17. work with this
  18. library you can read in the manual. */
  19. $curl=curl_init(); #Save the cURL session descriptor
  20. #Set the necessary parameters for the cURL session
  21. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  22. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  23. curl_setopt($curl,CURLOPT_HTTPHEADER,['Accept: application/json']);
  24. curl_setopt($curl,CURLOPT_URL,$link);
  25. curl_setopt($curl,CURLOPT_HEADER,false);
  26. curl_setopt($curl,CURLOPT_POSTFIELDS, http_build_query($data));
  27. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  28. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  29. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  30. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  31. curl_close($curl);
  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, 201 or 204, we return an error message
  47.  if(!in_array($code, [200, 201, 204])
  48.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  49. }
  50. catch(Exception $E)
  51. {
  52.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  53. }

List of incoming leads

A method for obtaining a list of incoming leads with the possibility of filtering and paging. Restriction on data returned on one page (offset) - 500 requests.

Method URL

GET / api / v2 / incoming_leads

Query Parameters
Parameter Description
page_size Number of selectable rows (system limit 500)
PAGEN_1 Selection Page
categories An array containing the categories for which you want to select (sip, mail, forms, chat)
order_by An array of one element. Key - field for sorting (created_at, for example), value (asc, desc) - sorting direction
pipeline_id The identifier of the pipeline from which to select
Response parameters
Parameter Type Description
_embedded array An array containing information adjacent to the query
_embedded/items array An array containing information for each individual element
source_name
require
string Name of the source of the request
uid
require
string The unique identifier of the request
created_at timestamp Date and time the request was created
category string Category, sip or form
incoming_entities/leads array An array containing information for creating a new lead. Can contain all the parameters and Custom fieldss available to "leads" on the account.
incoming_entities/contacts array An array containing information for creating a new contact. Can contain all the parameters and Custom fieldss available to "Contacts" on the account.
incoming_entities/companies array An array containing information for creating a new company. Can contain all the parameters and Custom fieldss available to "Companies" on the account.
incoming_lead_info/to int The identifier of the user who received the call
incoming_lead_info/from string External phone number
incoming_lead_info/date timestamp Date and time of the call
incoming_lead_info/duration int Call duration
incoming_lead_info/link string Link to call recording
incoming_lead_info/service_code string The code of the widget or service through which the call was made
incoming_lead_info/form_id int Form identifier
incoming_lead_info/form_page string The address of the page on which the form is located
incoming_lead_info/ip string The IP address on which the form is located
incoming_lead_info/form_name string Form name
incoming_lead_info/form_send_at timestamp Date and time of sending data via form
incoming_lead_info/referer string The parameter contains information from where to go to the page where the form 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

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/incoming_leads?login=name@team.amocrm.com&api_key=xxxxxx",
  5.          method: "get"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             category: "sip",
  12.             uid: "86c4ff85844722b75fcd74699b5a1ce474f7f73e272395b301ca87b36a33",
  13.             source_name: "686",
  14.             created_at: 1509609502,
  15.             incoming_lead_info: {
  16.                from: "15315",
  17.                to: "8152",
  18.                date: 1509570000,
  19.                duration: "50",
  20.                link: "example.com",
  21.                service_code: "CkKwPam6"
  22.             },
  23.             incoming_entities: {
  24.                leads: [
  25.                   {
  26.                      name: "Lead"
  27.                   }
  28.                ]
  29.             }
  30.          },
  31.          {
  32.             category: "form",
  33.             uid: "3b89a37ee72c329753750d9c3b7613a96aefa88e7d6065e383986e353d17",
  34.             source_name: "eterdgf",
  35.             created_at: 1509610029,
  36.             incoming_lead_info: {
  37.                form_id: "154613",
  38.                form_name: "Application",
  39.                form_page: "example.com",
  40.                ip: "48221",
  41.                form_send_at: 1509610030,
  42.                referer: null
  43.             },
  44.             incoming_entities: {
  45.                leads: [
  46.                   {
  47.                      name: "Lead",
  48.                      custom_fields: [
  49.                         {
  50.                            id: 4399916,
  51.                            values: [
  52.                               {
  53.                                  value: "3692245"
  54.                               }
  55.                            ],
  56.                            is_system: false
  57.                         }
  58.                      ]
  59.                   }
  60.                ]
  61.             }
  62.          }
  63.       ]
  64.    }
  65. }
Example integration
  1. /* First, we need to initialize the data needed to compose the query. */
  2. $subdomain='test'; #Our account is a subdomain
  3. #Generate a link for the request
  4. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads';
  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
  8. in the way that you want. */
  9. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads?api_key='.$api_key.'&login='.$login.'&page_size=15';
  10. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  11. work with this
  12. library you can read in the manual. */
  13. $curl=curl_init(); #Save the cURL session descriptor
  14. #Set the necessary parameters for the cURL session
  15. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  16. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  17. curl_setopt($curl,CURLOPT_HTTPHEADER,['Accept: application/json']);
  18. curl_setopt($curl,CURLOPT_URL,$link);
  19. curl_setopt($curl,CURLOPT_HEADER,false);
  20. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  21. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  22. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  23. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  24. curl_close($curl);
  25. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  26. $code=(int)$code;
  27. $errors=array(
  28.   301=>'Moved permanently',
  29.   400=>'Bad request',
  30.   401=>'Unauthorized',
  31.   403=>'Forbidden',
  32.   404=>'Not found',
  33.   500=>'Internal server error',
  34.   502=>'Bad gateway',
  35.   503=>'Service unavailable'
  36. );
  37. try
  38. {
  39.   #If the response code is not 200 or 204, we return an error message
  40.  if($code!=200 && $code!=204)
  41.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  42. }
  43. catch(Exception $E)
  44. {
  45.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  46. }

Summary information on incoming requests

Method for obtaining aggregated information about incoming requests with the possibility of filtering by date.

Method URL

GET / api / v2 / incoming_leads / summary

Query Parameters
Parameter Type Description
data/filter/date/from timestamp Start date
data/filter/date/to timestamp End Date
Response parameters
Parameter Type Description
sip int Number of unsorted calls received through incoming calls
forms int Number of unsorted requests received via web forms
mail int Number of unsorted requests received via mail
chat int Number of unsorted requests received via chat rooms
total int Total number of unsorted requests
avg_time timestamp Average request parsing time in seconds
>accepted int Total number of received requests
_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

Response Headers contains the following headers:

  • Content-Type:application/hal+json

  • Runtime-Timestamp: 1508320306

Response example
  1. {
  2.    sip: 34,
  3.    mail: 43,
  4.    form: 33,
  5.    chat: 0,
  6.    total: 110,
  7.    avg_time: 1204101653,
  8.    accepted: 45,
  9.    _links: {
  10.       self: {
  11.          href: "/api/v2/incoming_leads/summary?login=example@example.com&api_key=24dbfd65b23ff2ea13a988893be1da61",
  12.          method: "get"
  13.       }
  14.    }
  15. }
Example integration:
  1. $subdomain='test'; #Our account is a subdomain
  2. #Generate a link for the request
  3. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads/summary/';
  4. /* Note that you can pass other parameters in the reference that affect the output (see
  5. documentation).
  6. Therefore, we can replace the link given above with one of the following, or combine the parameters
  7. in the way that you want. */
  8. $link='https://'.$subdomain.'.amocrm.com/api/v2/incoming_leads/summary?api_key='.$api_key.'&login='.$login;
  9. /* We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  10. work with this
  11. library you can read in the manual. */
  12. $curl=curl_init(); #Save the cURL session descriptor
  13. #Set the necessary parameters for the cURL session
  14. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  15. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  16. curl_setopt($curl,CURLOPT_HTTPHEADER,['Accept: application/json']);
  17. curl_setopt($curl,CURLOPT_URL,$link);
  18. curl_setopt($curl,CURLOPT_HEADER,false);
  19. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  20. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  21. $out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
  22. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  23. curl_close($curl);
  24. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  25. $code=(int)$code;
  26. $errors=array(
  27.   301=>'Moved permanently',
  28.   400=>'Bad request',
  29.   401=>'Unauthorized',
  30.   403=>'Forbidden',
  31.   404=>'Not found',
  32.   500=>'Internal server error',
  33.   502=>'Bad gateway',
  34.   503=>'Service unavailable'
  35. );
  36. try
  37. {
  38.   #If the response code is not 200 or 204, we return an error message
  39.  if($code!=200 && $code!=204)
  40.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  41. }
  42. catch(Exception $E)
  43. {
  44.   die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  45. }