Skip to main content
Tags let you label and categorize contacts for filtering, segmentation, and workflow routing. Each contact can have up to 5 tags. You create and manage tags through the Tags API, then assign them to contacts via the contact create or update endpoints.

​
The Tag object

​
id
integer
Unique identifier for the tag.
​
tag
string
The tag label text.
​
color
string
Hex color code for the tag’s visual indicator in the Heymarket UI.
​
team_id
integer
ID of the team that owns this tag.
​
created
string
ISO 8601 timestamp when the tag was created.
​
updated
string
ISO 8601 timestamp when the tag was last updated.
​
rev
integer
Revision number. Increments on each update.

​
Create a tag

POST /v1/tag
​
tag
string
required
The label text for the new tag.
​
color
string
Hex color code for the tag (e.g., "#FF5733").
curl --request POST \
  --url https://api.heymarket.com/v1/tag \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "tag": "VIP",
    "color": "#FFD700"
  }'

{
  "id": 55,
  "rev": 1,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

​
Get a tag

GET /v1/tag/{id}
​
id
integer
required
The ID of the tag to retrieve.
curl --request GET \
  --url https://api.heymarket.com/v1/tag/55 \
  --header 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 55,
  "tag": "VIP",
  "color": "#FFD700",
  "team_id": 7,
  "created": "2024-01-10T08:00:00Z",
  "updated": "2024-01-10T08:00:00Z",
  "rev": 1
}

​
List tags

POST /v1/tags Returns up to 30 of your most recent tags. Pass a date to paginate through older results.
​
date
string
RFC 3339 timestamp. Returns tags updated before this date.
curl --request POST \
  --url https://api.heymarket.com/v1/tags \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}'

[
  {
    "id": 55,
    "tag": "VIP",
    "color": "#FFD700",
    "team_id": 7,
    "created": "2024-01-10T08:00:00Z",
    "updated": "2024-01-10T08:00:00Z",
    "rev": 1
  }
]

​
Delete a tag

DELETE /v1/tag/{id}
​
id
integer
required
The ID of the tag to delete.
curl --request DELETE \
  --url https://api.heymarket.com/v1/tag/55 \
  --header 'Authorization: Bearer YOUR_API_KEY'

"ok"

​
Assigning tags to contacts

To assign tags to a contact, include the tags array in the request body when creating or updating a contact. Each element must be an object with a tag_id field. 
{
  "tags": [
    {"tag_id": 55},
    {"tag_id": 56}
  ]
}
Each contact supports a maximum of 5 tags. Providing more than 5 tag entries will result in an error.