Tags

The Tags API provides a simple interface to manage tags. The API allows you to create, delete and update your tags. You can retrieve a single tag, a list of all tags, and search for tags.

Properties

Attribute Description
id number readonly

Unique identifier of the tag.

creator_id number readonly

User ID of the tag’s creator.

name string

Name of the tag.

resource_type string

Type name of the resource the tag is attached to.

Possible values:

  • lead
  • contact
  • deal
created_at string readonly

Date and time of creation in UTC (ISO8601 format).

updated_at string readonly

Date and time of the last update in UTC (ISO8601 format).


Endpoints


Retrieve all tags

Returns all tags available to the user, according to the parameters provided.

Parameters

Attribute Description
page number optional

Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.

e.g. ?page=2
per_page number optional

Number of records to return per page. The default limit is 25 and the maximum number that can be returned is 100.

e.g. ?per_page=20
sort_by string optional

A field to sort by. The default order is ascending. If you want to change the sort order to descending, append :desc to the field e.g. sort_by=name:desc.

Possible values:

  • name
  • updated_at
  • created_at
e.g. ?sort_by=created_at
ids string optional

Comma-separated list of deal tag IDs to be returned in a request.

e.g. ?ids=1,2,3
creator_id number optional

User ID. Returns all tags created by that user.

e.g. ?creator_id=1
name string optional

Name of the tag to search for. This parameter is used in a strict sense.

e.g. ?name=publisher
resource_type string optional

Type name of resource to search for.

Possible values:

  • lead
  • contact
  • deal
e.g. ?resource_type=lead

Create a tag

Creates a new tag. Notice the tag’s name must be unique within the scope of the resource_type.

Parameters

Attribute Description
name string required

Must be unique within the scope of the resource_type.

e.g. "name": "important"
resource_type string required
e.g. "resource_type": "contact"

Retrieve a single tag

Returns a single tag available to the user according to the unique ID provided. If the specified tag does not exist, this query will return an error.

Parameters

Attribute Description
id number required

Unique identifier of the tag.


Update a tag

Updates a tag’s information. If the specified tag does not exist, this query will return an error.

Notice if you want to update a tag, you must make sure the tag’s name is unique within the scope of the specified resource.

Parameters

Attribute Description
id number required

Unique identifier of the tag.

name string optional

Must be unique within the scope of the resource_type.

e.g. "name": "super important"
resource_type string optional
e.g. "resource_type": "contact"

Delete a tag

Deletes an existing tag. If the specified tag is assigned to any resource, we will remove this tag from all such resources. If the specified tag does not exist, this query will return an error. This operation cannot be undone.

Parameters

Attribute Description
id number required

Unique identifier of the tag.