Tags

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

Table of Contents

• Common information
• List of entity tags
• Adding tags for a particular entity type
• Adding tags to an entity
• Deleting tags from an entity

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 correspondence to the user rights.

GET parameters

An example of the request

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

        
https://example.kommo.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 parameters

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

Response example

        
{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads/tags?filter[id][]=2707&filter[id][]=2709&page=1&limit=50"
        },
        "next": {
            "href": "https://example.kommo.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 entity specified in the method URL.

Limitations

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

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 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 correspondence 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

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 parameters

Method returns a collection of updated entities.

Response example

        
{
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 167353,
                "updated_at": 1588928155,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/167353"
                    }
                }
            },
            {
                "id": 167355,
                "updated_at": 1588928155,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.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 correspondence 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.

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 parameters

Method returns a collection of updated entities.

Response example

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