Links between entities
In this section we will describe all available methods for working with links between entities (leads, contacts, companies, and customers)
Table of Contents
Common information
Available links differ based on the entity type
- Available for the lead entity: contacts, companies, lists elements
- Available for the contact entity: companies, customers, lists elements
- Available for the company entity: contacts, leads, customers, lists elements
- Available for the customer entity: contacts, companies, lists elements
Linked entities list
Method
GET /api/v4/leads/{entity_id}/links
GET /api/v4/contacts/{entity_id}/links
GET /api/v4/companies/{entity_id}/links
GET /api/v4/customers/{entity_id}/links
Description
This method allows to get a list of linked entites by the ID of the main entity.
Limitations
Method is available in correspondense to the user rights.
GET parameters
Parameter | Data type | Description |
---|---|---|
filter | object | Filter |
filter[to_entity_id] | int | Filter by the ID of the linked entity. The filter is passed with the filter[to_entity_type] filter |
filter[to_entity_type] | string | Filter by the type of the linked entity. The filter is passed with the filter[to_entity_id] filter |
filter[to_catalog_id] | int | Filter by the ID of the linked entity catalog |
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 | User is not authorized |
400 | Invalid data given. Details are available in the request response |
Response parameters
Method returns a collection of links models. The properties of a model are listed below.
Parameter | Data type | Description |
---|---|---|
to_entity_id | int | Linked entity ID |
to_entity_type | string | Linked entity types (leads, contacts, companies, customers, catalog_elements) |
metadata | object|null | Linked entity metadata |
metadata[main_contact] | bool | Defines whether the contact is main for the entity |
metadata[quantity] | int | Quantity of the linked catalog elements |
metadata[catalog_id] | int | Catalog ID |
Response example
{
"_total_items": 4,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/7593303/links?page=1&limit=50"
}
},
"_embedded": {
"links": [
{
"to_entity_id": 597393,
"to_entity_type": "catalog_elements",
"metadata": {
"quantity": 1,
"catalog_id": 4521
}
},
{
"to_entity_id": 11069775,
"to_entity_type": "contacts",
"metadata": {
"main_contact": true
}
},
{
"to_entity_id": 11271233,
"to_entity_type": "contacts",
"metadata": {
"main_contact": false
}
},
{
"to_entity_id": 11271229,
"to_entity_type": "companies",
"metadata": null
}
]
}
}
Linking entities
Method
POST /api/v4/leads/{entity_id}/link
POST /api/v4/contacts/{entity_id}/link
POST /api/v4/companies/{entity_id}/link
POST /api/v4/customers/{entity_id}/link
Description
This method allows to link entities to the main entity.
Limitations
Method is available in correspondense to the user rights.
Request header
Content-Type: application/json
Request parameters
Parameter | Data type | Description |
---|---|---|
to_entity_id | int | Linked entity ID |
to_entity_type | string | Linked entity type (leads, contacts, companies, customers, catalog_elements) |
metadata | object|null | Linked entity metadata |
metadata[catalog_id] | int | Catalog ID |
metadata[quantity] | int | Quantity of the linked catalog elements |
metadata[is_main] | bool | Defines whether the contact is main for the entity |
metadata[updated_by] | int | ID of the user performing the linking |
An example of the request
[
{
"to_entity_id": 10,
"to_entity_type": "catalog_elements",
"metadata": {
"quantity": 1,
"catalog_id": 1026
}
},
{
"to_entity_id": 457282,
"to_entity_type": "contacts",
"metadata": {
"is_main": true,
}
}
]
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 | Entities linked successfully |
403 | Insufficient rights to call this method |
401 | User is not authorized |
400 | Invalid data given. Details are available in the request response |
Response parameters
Method returns a collection of linked entities models. Model parameters are similar to the entity links request parameters.
Response example
{
"_total_items": 2,
"_links": {
"self": {
"href": "https://example.amocrm.com/api/v4/leads/14158851/links"
}
},
"_embedded": {
"links": [
{
"entity_id": 14158851,
"entity_type": "leads",
"to_entity_id": 10,
"to_entity_type": "catalog_elements",
"metadata": {
"quantity": 1,
"catalog_id": 1026
}
},
{
"entity_id": 14158851,
"entity_type": "leads",
"to_entity_id": 457282,
"to_entity_type": "contacts",
"metadata": {
"main_contact": true
}
}
]
}
}
Unlinking entities
Method
POST /api/v4/leads/{entity_id}/unlink
POST /api/v4/contacts/{entity_id}/unlink
POST /api/v4/companies/{entity_id}/unlink
POST /api/v4/customers/{entity_id}/unlink
Description
This method allows to unlink entites from the main entity.
Limitations
Method is available in correspondense to the user rights.
Request header
Content-Type: application/json
Request parameters
Parameter | Data type | Description |
---|---|---|
to_entity_id | int | Linked entity ID |
to_entity_type | string | Linked entity type (leads, contacts, companies, customers, catalog_elements) |
metadata | object|null | Linked entity metadata |
metadata[catalog_id] | int | Catalog ID |
metadata[updated_by] | int | ID of the user performing the unlinking |
An example of the request
[
{
"to_entity_id": 10,
"to_entity_type": "catalog_elements",
"metadata": {
"catalog_id": 1026
}
},
{
"to_entity_id": 457282,
"to_entity_type": "contacts",
}
]
HTTP response codes.
Response code | Case |
---|---|
204 | Entities unlinked successfully |
403 | Insufficient rights to call this method |
401 | User is not authorized |
400 | Invalid data given. Details are available in the request response |
Response parameters
Method does not return a body.