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 entities by the ID of the main entity.

Limitations

The method is available in correspondence 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 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 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

The method is available in correspondence 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 The 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 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 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 entities from the main entity.

Limitations

The method is available in correspondence 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 The 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 The user is not authorized
400 Invalid data are given. Details are available in the request-response

Response parameters

The method does not return a body.