Tags

In this section we will decribe how to work with tags via API

Table of Contents

Common information

  • The tags directory is divided by the entity type. A tag will have a different ID for different entities
  • Tags functionality is available for the following entities: leads, contacts, companies, and customers

List of entity tags

Method

GET /api/v4/{entity_type:leads|contacts|companies|customers}/tags

Description

This method allows to get the list of entity tags on the account.

Limitations

Method is available in correspondense 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 of one request (limit – 250)
filter object Filter
filter[name] string Filter by the exact tag name. Only one name can be passed
filter[id] int|array Filter by tag ID. A single tag ID or an array of IDs can be passed
query string Allows to perform a fulltext search by the tag name

An example of the request

In the following example we will get lead tags filtered by ID.

        
https://example.amocrm.com/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709
        
    

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
204 No data found
401 User is not authorized

Response parameters

Method returns a collection of tag models. The properties of the tag model are listed below

Parameter Data type Description
id int Tag ID
name string Tag name

Response example

        
{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709&page=1&limit=50"
        },
        "next": {
            "href": "https://example.amocrm.com/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709&page=2&limit=50"
        }
    },
    "_embedded": {
        "tags": [
            {
                "id": 2707,
                "name": "Site request"
            },
            {
                "id": 2709,
                "name": "Tech support"
            }
        ]
    }
}
        
    

Adding tags for a particular entity type

Method

POST /api/v4/{entity_type:leads|contacts|companies|customers}/tags

Description

This method allows to add multiple tags for a particular enitity specified in the method URL.

Limitations

Method is available in correspondense to the user rights.

Request header

Content-Type: application/json

Request parameters

To add a tag, the “name” parameter should be passed. If the passed tag name already exists, this tag’s ID will be returned in the responce

Parameter Data type Description
name string Tag name
request_id string Field that will be returned unchanged in the response and will not be saved. Is not a mandatory field

An example of the request

        
[
    {
        "name": "Tag 1"
    },
    {
        "name": "Tag 2",
        "request_id": "my_request_id"
    },
    {
        "name": "Tag 3"
    }
]
        
    

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 Tags added successfully
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method return a collection of created tags.

Response example

        
{
    "_total_items": 3,
    "_embedded": {
        "tags": [
            {
                "id": 263807,
                "name": "Tag 1",
                "request_id": "0"
            },
            {
                "id": 263809,
                "name": "Tag 2",
                "request_id": "my_request_id"
            },
            {
                "id": 263811,
                "name": "Tag 3",
                "request_id": "2"
            }
        ]
    }
}
        
    

Adding tags to an entity

Method

PATCH /api/v4/{entity_type:leads|contacts|companies|customers}

Description

This method allows updating multiple entities.
To update a particular entity, you can add the entity ID into the method URL (e.g. /api/v4/leads/{id}).
When updating multiple entities, an array of entity objects is passed. In case with a singular entity, the entity model is passed.

Limitations

Method is available in correspondense to the user rights.

Request header

Content-Type: application/json

Request parameters

It is important to note that all entity tags should be passed. If already attached tags are not passed, they will be detached from the entity

Parameter Data type Description
_embedded[tags] array|null Added tags data
_embedded[tags][0] object Tag model. Either “id” or “name” parameter is required
_embedded[tags][0][id] int Tag ID
_embedded[tags][0][name] string Tag name

An example of the request

In the following example we’ll add tags to 2 leads using the /api/v4/leads method.

        
[
    {
        "id": 167353,
        "_embedded": {
            "tags": [
                {
                    "id": 263807
                }
            ]
        }
    },
    {
        "id": 167355,
        "_embedded": {
            "tags": [
                {
                    "name": "Tag 2"
                }
            ]
        }
    }
]
        
    

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 updated successfully
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of updated entities.

Response example

        
{
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 167353,
                "updated_at": 1588928155,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/167353"
                    }
                }
            },
            {
                "id": 167355,
                "updated_at": 1588928155,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/167355"
                    }
                }
            }
        ]
    }
}
        
    

Deleting tags from an entity

Method

PATCH /api/v4/{entity_type:leads|contacts|companies|customers}

Description

This method allows updating multiple entities.
To update a particular entity, you can add the entity ID into the method URL (e.g. /api/v4/leads/{id}).
When updating multiple entities, an array of entity objects is passed. In case with a singular entity, the entity model is passed.

Limitations

Method is available in correspondense to the user rights.

Request header

Content-Type: application/json

Request parameters

To detach tags from an entity, the property _embedded[tags] with the value “null” should be passed.

Parameter Data type Description
_embedded[tags] array|null Tags data

An example of the request

In the following example, we will detach tags from a lead using the /api/v4/leads/{id} method.

        
{
    "_embedded": {
        "tags": null
    }
}
        
    

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 updated successfully
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of updated entities.

Response example

        
{
    "id": 167353,
    "updated_at": 1588928155,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/167353"
        }
    }
}