Incoming Leads
In this section, we will describe all available methods for working with Incoming leads via API.
Table of Contents
- Common information
- Incoming leads list
- Getting an incoming lead by its UID
- Adding the sip (call) type incoming leads
- Adding the form type incoming leads
- Accepting incoming leads
- Declining incoming leads
- Linking incoming leads
- Incoming leads summary information
- Metadata objects description
Common information
- Incoming leads is a system stage of the Leads pipeline with additional functionality
- This stage accumulates leads from different sources to be sorted out by managers
- There are 4 categories for the Incoming leads: chats, forms, sip (call), and mail
- Only 2 types are available to add via API: forms and sip.
- Incoming leads of the chats and mail types are added via built-in tools (chats and mail integrations)
- When adding an Incoming lead, contact, company data, and metadata (call or form info) can be passed
- Until the Incoming lead is accepted, contacts and companies linked to it are unavailable in the Lists section
- There can’t be 2 of the same entity in the Incoming leads. If you attempt to add data that already exists, you will receive an error
- An Incoming lead can be accepted, declined, or linked to an existing Lead or Customer. Only Incoming leads of the chat type can be linked
Incoming leads list
Method
GET /api/v4/leads/unsorted
Description
This method allows getting a list of incoming leads in the account.
Limitations
The method is available in correspondence to the user rights.
GET parameters
Parameter | Data type | Description |
---|---|---|
page | int | Sample page |
limit | int | The number of the entities returned in the response to one request (limit – 250) |
filter | object | Filter |
filter[uid] | string|array | Filter by the incoming lead UID. Either a single UID or an array of UIDs can be passed |
filter[category] | array | Filter by the incoming leads categories (sip, mail, forms, chats) |
filter[pipeline_id] | int | Filter by the pipeline ID |
order | object | List elements sorting. Fields available to sort by: created_at, updated_at. Values available to sort by: asc, desc. An example: /api/v4/leads/unsorted?order[created_at]=asc |
An example of the request
In the following example, we will get a single incoming lead list.
https://example.amocrm.com/api/v4/leads/unsorted?filter[uid]=98fb033cefde74f5de1a5d3980a2a2d108037
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | The user is not authorized |
Response parameters
The method returns a collection of incoming lead models. The properties of the model are listed below.
Parameter | Data type | Description |
---|---|---|
uid | string | Incoming lead UID |
source_uid | string | Incoming lead source UID. Generated by the integration |
source_name | string | Incoming lead source name |
category | string | Incoming lead category: sip, mail, chats, forms |
pipeline_id | int | ID of the pipeline the incoming lead is located in |
created_at | int | Incoming lead creation date in the format of Unix Timestamp |
metadata | object | Incoming lead metadata. Each type has its own parameters. They are described in detail here |
account_id | int | Account ID |
_embedded | object | Embedded entities data |
_embedded[contacts] | array | Linked contact data array. Always consists of 1 object |
_embedded[contacts][0] | object | Contact model |
_embedded[contacts][0][id] | int | Contact ID |
_embedded[companies] | array | Linked company data array. Always consists of 1 object |
_embedded[companies][0] | object | Company model |
_embedded[companies][0][id] | int | Company ID |
_embedded[leads] | array | Lead data array. Always consists of 1 object |
_embedded[leads][0] | object | Lead model |
_embedded[leads][0][id] | int | Lead ID |
Response example
{
"_page": 1,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/unsorted?filter[uid]=98fb033cefde74f5de1a5d3980a2a2d108037"
}
},
"_embedded": {
"unsorted": [
{
"uid": "98fb033cefde74f5de1a5d3980a2a2d108037",
"source_uid": null,
"source_name": "UIS",
"category": "sip",
"pipeline_id": 2194576,
"created_at": 1583156937,
"metadata": {
"from": "14155551234",
"phone": 14155551234,
"called_at": 1583156916,
"duration": "0",
"link": null,
"service_code": "uis_widget"
},
"account_id": 123312,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/unsorted/98fb033cefde74f5de1a5d3980a2a2d108037"
}
},
"_embedded": {
"contacts": [
{
"id": 13176707,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/contacts/13176707"
}
}
}
],
"leads": [
{
"id": 7002787,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/7002787"
}
}
}
],
"companies": []
}
}
]
}
}
Getting an incoming lead by its UID
Method
GET /api/v4/leads/unsorted/{uid}
Description
This method allows getting a particular incoming lead data by its UID.
Limitations
The method is available in correspondence to the user rights.
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | The user is not authorized |
Response parameters
The method returns a model of the incoming lead. The properties of the model are listed below.
Parameter | Data type | Description |
---|---|---|
uid | string | Incoming lead UID |
source_uid | string | Incoming lead source UID. Generated by the integration |
source_name | string | Incoming lead source name |
category | string | Incoming lead category: sip, mail, chats, forms |
pipeline_id | int | The ID of the pipeline the incoming lead is located in |
created_at | int | Incoming lead creation date in the format of Unix Timestamp |
metadata | object | Incoming lead metadata. Each type has its own parameters. They are described in detail here |
account_id | int | Account ID |
_embedded | object | Embedded entities data |
_embedded[contacts] | array | Linked contact data array. Always consists of 1 object |
_embedded[contacts][0] | object | Contact model |
_embedded[contacts][0][id] | int | Contact ID |
_embedded[companies] | array | Linked company data array. Always consists of 1 object |
_embedded[companies][0] | object | Company model |
_embedded[companies][0][id] | int | Company ID |
_embedded[leads] | array | Lead data array. Always consists of 1 object |
_embedded[leads][0] | object | Lead model |
_embedded[leads][0][id] | int | Lead ID |
Response example
{
"uid": "aa401affb0094076b7449008363c1dc77d6790ad13fb5b08176dc46daa18",
"source_uid": "my_unique_uid",
"source_name": "Source name",
"category": "forms",
"pipeline_id": 3166396,
"created_at": 1588840852,
"metadata": {
"form_id": "my_best_form",
"form_name": "Feedback form",
"form_page": "https://example.com/form",
"ip": "192.168.0.1",
"form_sent_at": "1570178452",
"referer": "https://google.com/search",
"visitor_uid": null
},
"account_id": 28805383,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/unsorted/aa401affb0094076b7449008363c1dc77d6790ad13fb5b08176dc46daa18"
}
},
"_embedded": {
"contacts": [
{
"id": 9567221,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/contacts/9567221"
}
}
}
],
"leads": [
{
"id": 6414851,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/6414851"
}
}
}
],
"companies": []
}
}
Adding the sip (call) type incoming leads
Method
POST /api/v4/leads/unsorted/sip
Description
This method allows adding multiple or singular incoming leads into the account.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
It is important to note that added calls should be inbound.
All fields except created_at, pipeline_id are mandatory.
Parameter | Data type | Description |
---|---|---|
source_uid | string | Incoming lead source UID. Generated by the integration |
source_name | string | Incoming lead source name |
pipeline_id | int | The ID of the pipeline the incoming lead will be added to |
created_at | int | Incoming lead creation date in the format of Unix Timestamp |
metadata | object | Incoming lead metadata. Each type has its own parameters. They are described in detail here |
_embedded | object | Embedded entities data |
_embedded[contacts] | array | Linked contact data array. Always consists of 1 object |
_embedded[contacts][0] | object | Contact model. Corresponds to the model that’s passed when adding a contact |
_embedded[companies] | array | Linked company data array. Always consists of 1 object |
_embedded[companies][0] | object | Company model. Corresponds to the model that’s passed when adding a company |
_embedded[leads] | array | Lead data array. Always consists of 1 object |
_embedded[leads][0] | object | Lead model. Corresponds to the model that’s passed when adding a lead |
request_id | string | The field that will be returned unchanged in the response and will not be saved. Is not a mandatory field |
An example of the request
[
{
"request_id": "123",
"source_name": "Acme Co.",
"source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
"pipeline_id": 2194576,
"created_at": 1510261200,
"_embedded": {
"leads": [
{
"name": "Tech maintenance",
"price": 5000,
"custom_fields_values": [
{
"field_id": 284785,
"values": [
{
"value": "Custom field"
}
]
}
],
"_embedded": {
"tags": [
{
"id": 263809
}
]
}
}
],
"contacts": [
{
"name": "Example contact"
}
],
"companies": [
{
"name": "Acme Co."
}
]
},
"metadata": {
"is_call_event_needed": true,
"uniq": "a1fe231cc88e64ba2e8822ba2b3ewrw",
"duration": 54,
"service_code": "CkAvbEwPam6sad",
"link": "https://example.com",
"phone": 14155551234,
"called_at": 1510261200,
"from": "onlinePBX"
}
}
]
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming leads added successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns a collection of created incoming leads.
Response example
{
"_total_items": 1,
"_embedded": {
"unsorted": [
{
"uid": "aa401affb0094076b74442bc3f401d53e103f264d6668fd3ecfd5acef42f",
"account_id": 28805383,
"request_id": "123",
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/unsorted/aa401affb0094076b74442bc3f401d53e103f264d6668fd3ecfd5acef42f"
}
},
"_embedded": {
"contacts": [
{
"id": 11075541,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/contacts/11075541"
}
}
}
],
"leads": [
{
"id": 7706509,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/7706509"
}
}
}
],
"companies": []
}
}
]
}
}
Adding the form type incoming leads
Method
POST /api/v4/leads/unsorted/forms
Description
This method allows adding multiple or singular incoming leads into the account.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
All fields except created_at, pipeline_id are mandatory.
Parameter | Data type | Description |
---|---|---|
source_uid | string | Incoming lead source UID. Generated by the integration |
source_name | string | Incoming lead source name |
pipeline_id | int | The ID of the pipeline the incoming lead will be added to |
created_at | int | Incoming lead creation date in the format of Unix Timestamp |
metadata | object | Incoming lead metadata. Each type has its own parameters. They are described in detail here |
_embedded | object | Embedded entities data |
_embedded[contacts] | array | Linked contact data array. Always consists of 1 object |
_embedded[contacts][0] | object | Contact model. Corresponds to the model that’s passed when adding a contact |
_embedded[companies] | array | Linked company data array. Always consists of 1 object |
_embedded[companies][0] | object | Company model. Corresponds to the model that’s passed when adding a company |
_embedded[leads] | array | Lead data array. Always consists of 1 object |
_embedded[leads][0] | object | Lead model. Corresponds to the model that’s passed when adding a lead |
request_id | string | The field that will be returned unchanged in the response and will not be saved. Is not a mandatory field |
An example of the request
[
{
"request_id": "123",
"source_name": "Acme Co.",
"source_uid": "a1fee7c0fc436088e64ba2e8822ba2b3",
"pipeline_id": 2194576,
"created_at": 1590830520,
"_embedded": {
"leads": [
{
"name": "Tech maintenance",
"visitor_uid": "5692210d-58d0-468c-acb2-dce7f93eef87",
"price": 5000,
"custom_fields_values": [
{
"field_id": 284785,
"values": [
{
"value": "Custom field"
}
]
}
],
"_embedded": {
"tags": [
{
"name": "Example tag"
}
]
}
}
],
"contacts": [
{
"name": 234,
"first_name": "123213",
"last_name": 234,
"custom_fields_values": [
{
"field_code": "PHONE",
"values": [
{
"value": "+14155551234"
}
]
}
]
}
],
"companies": [
{
"name": "Acme Co."
}
]
},
"metadata": {
"ip": "123.222.2.22",
"form_id": "a1fee7c0fc436088e64ba2e8822ba2b3ewrw",
"form_sent_at": 1590830520,
"form_name": "Application form",
"form_page": "https://example.com",
"referer": "https://www.google.com/search?&q=elon+musk"
}
}
]
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming leads added successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns a collection of created incoming leads.
Response example
{
"_total_items": 1,
"_embedded": {
"unsorted": [
{
"uid": "69035fda95c38bf3a281e846652217aade38692a5cf9d2b312e3724f78bc",
"account_id": 28805383,
"request_id": "123",
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/unsorted/69035fda95c38bf3a281e846652217aade38692a5cf9d2b312e3724f78bc"
}
},
"_embedded": {
"contacts": [
{
"id": 11075543,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/contacts/11075543"
}
}
}
],
"leads": [
{
"id": 7706511,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/7706511"
}
}
}
],
"companies": []
}
}
]
}
}
Accepting incoming leads
Method
POST /api/v4/leads/unsorted/{uid}/accept
Description
This method allows to accept an incoming lead.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
There are no mandatory parameters to accept an incoming lead, however, optional data can be passed.
Parameter | Data type | Description |
---|---|---|
user_id | int | The ID of the user who will be set as the entity creator |
status_id | int | The ID of the stage where the lead will be located after an incoming lead is accepted |
An example of the request
In the following example, we will accept an Incoming lead using the /api/v4/leads/unsorted/{uid}/accept method.
The Incoming lead will be accepted on behalf of the user with ID 123123.
{
"user_id": 123123,
"status_id": 30846280
}
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming lead accepted successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
404 | Incoming lead with this UID was not found |
Response parameters
The method returns a model of the accepted incoming lead and created entities.
Response example
{
"uid": "3cvd1de2ebfsd152fd6a465cd3e586cbdba6827",
"pipeline_id": 31634,
"category": "mail",
"created_at": 1589165593,
"_embedded": {
"leads": [
{
"id": 9944789,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/9944789"
}
}
}
],
"contacts": [
{
"id": 16522451,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/contacts/16522451"
}
}
}
],
"companies": []
}
}
Declining incoming leads
Method
DELETE /api/v4/leads/unsorted/{uid}/decline
Description
This method allows to decline an incoming lead.
Limitations
The method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
There are no mandatory parameters to decline an incoming lead, however, optional data can be passed.
Parameter | Data type | Description |
---|---|---|
user_id | int | The ID of the user performing the decline |
An example of the request
{
"user_id": 123123
}
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming lead deleted successfully |
403 | Insufficient rights to call this method |
404 | Incoming lead with this UID was not found |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns a model of the declined incoming lead and entities that were moved to the bin.
Response example
{
"uid": "98bc1d1de2f960a2ad0e34b52823",
"pipeline_id": 1394576,
"category": "mail",
"created_at": 1589115506,
"_embedded": {
"leads": [
{
"id": 9937533,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/9937533"
}
}
}
],
"contacts": [
{
"id": 163141,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/contacts/163141"
}
}
}
]
}
}
Linking incoming leads
Method
POST /api/v4/leads/unsorted/{uid}/link
Description
This method allows link an incoming lead to an existing lead or customer.
Limitations
- The method is available for administrator users only
- The method is available for incoming leads of the “chats” type only
Request header
Content-Type: application/json
Request parameters
To link an incoming lead, it is required to pass the “link” object.
Parameter | Data type | Description |
---|---|---|
user_id | int | The ID of the user who performs the link |
link | object | An object containing the data of the entity an incoming lead will be linked to |
link[entity_id] | int | The ID of the entity an incoming lead will be linked to |
link[entity_type] | string | Entity type: leads, customers |
link[metadata] | object | Action metadata |
link[metadata][contact_id] | int | The ID of the contact the incoming lead’s contact will be linked to |
An example of the request
{
"link": {
"entity_id": 93144801,
"entity_type": "leads"
}
}
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Incoming lead linked successfully |
401 | The user is not authorized |
400 | Invalid data are given. Details are available in the request-response |
Response parameters
The method returns the information about the performed action.
Response example
{
"uid": "d7faa21ce091fe0da05d8d4c2075090c1e9bfd4",
"_embedded": {
"leads": [
{
"id": 93144801,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/93144801"
}
}
}
]
}
}
Incoming leads summary information
Method
GET /api/v4/leads/unsorted/summary
Description
This method allows to get the incoming leads summary information.
Limitations
The method is available in correspondence to the user rights.
GET parameters
Parameter | Data type | Description |
---|---|---|
filter | object | Filter |
filter[uid] | string|array | Filter by the incoming lead UID. Either a single UID or an array of UIDs can be passed |
filter[created_at] | int|object | Filter by the creation date and the date when an incoming lead was accepted. The timestamp value can be passed. In that case, incoming leads created or accepted after the timestamp will be returned. The object of the following structure can also be passed to filter between “to” and “from” values: filter[created_at][from]=… and filter[created_at][to]=… |
filter[pipeline_id] | int | Filter by the pipeline ID |
An example of the request
https://example.amocrm.com/api/v4/leads/unsorted/summary?filter[created_at][from]=1589176500&filter[created_at][to]=1589176560&filter[pipeline_id]=2194576
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | The user is not authorized |
Response parameters
The method returns the summary information as an object.
Parameter | Data type | Description |
---|---|---|
total | int | Total number of incoming leads |
accepted | int | Total number of accepted incoming leads |
declined | int | Total number of declined incoming leads |
average_sort_time | int | Average sorting time in seconds |
categories | object | The number of incoming leads of a particular category |
Response example
{
"total": 168,
"accepted": 6,
"declined": 2,
"average_sort_time": 34521,
"categories": {
"sip": {
"total": 31
},
"mail": {
"total": 41
},
"forms": {
"total": 27
},
"chats": {
"total": 69
}
}
}
Metadata objects description
Incoming leads metadata of the sip (call) category
Parameter | Data type | Description |
---|---|---|
from | string | Call initiator |
phone | string | Call recipient |
called_at | int | Call date in the format of Unix Timestamp |
duration | int | Call duration |
link | string | A link to the call recording |
service_code | string | Service provider code |
is_call_event_needed | bool | This flag is not returned in the response but can be passed. If the “true” value is passed, the call event will be added to the entity card. |
Incoming leads metadata of the forms category
Parameter | Data type | Description |
---|---|---|
form_id | string | Integration’s form ID. |
form_name | string | Form name |
form_page | string | Web-page where the form is installed |
ip | string | The IP address of the request |
form_sent_at | int | Form submission timestamp is the format of Unix Timestamp |
referer | string | Web-page the applicant was redirected from to the form page |
Incoming leads metadata of the chats category
Parameter | Data type | Description |
---|---|---|
from | string | The name of the user who sent the message |
to | string | The ID of the page that received the message |
received_at | int | Message date in the format of Unix Timestamp |
service | string | Name of the service that delivered the message |
client | object | Message author data |
client[name] | string | Message sender name |
client[avatar] | string|null | Link to the sender’s avatar |
origin | object | Message source data |
origin[chat_id] | string | Chat ID in the chats service |
origin[ref] | string|null | Additional data from the chats service |
origin[visitor_uid] | string|null | UID of the user who sent the message |
last_message_text | string|null | The last message from the user |
source_name | string | Message source name |
Incoming leads metadata of the mail category
Parameter | Data type | Description |
---|---|---|
from | object | Email author data |
from[email] | string | Author email address |
from[name] | string | Author name |
received_at | int | Date when the email was received in the format of Unix Timestamp |
subject | string | Email subject |
thread_id | int | Thread ID in the mail service |
message_id | int | Email ID in the mail service |
content_summary | string | Email content summary |