This article describes all fields available through the Tag API. Use this as a reference when reading, creating, or updating tags.
Overview
The Tag API lets you manage tags (also called interests) in your Envoke account programmatically. Tags are used to segment contacts based on topics, preferences, or areas of interest. Contacts can be assigned to or removed from tags in bulk via the contacts endpoints.
Tags can be organised into groups, given a plain-text description for internal reference, and configured with translated display names for public-facing contexts such as website subscription forms.
All endpoints require HTTP Basic Auth using your API ID and API Key.
Fields
Field | Type | Read-only | Required on Create | Description |
| string | Yes | — | Unique identifier assigned on creation. |
| string | Yes | — | Externally visible identifier used in public-facing integrations. |
| string | No | Yes | The tag name. |
| string | No | No | Group the tag belongs to. Empty string ( |
| string | No | No | Internal description of the tag. |
| object | No | No | Translated display labels keyed by language ISO code. |
Field Details
id
Type: String
Read-only: Yes — assigned automatically on creation.
Example:
"42"
Used to identify the tag in update, delete, and contact assignment requests.
external_id
Type: String
Read-only: Yes — assigned automatically on creation.
Example:
"a1b2c3d4e5f6"
An externally visible identifier used in public-facing contexts. Not the same as id.
name
Type: String
Read-only: No — updatable via PATCH.
Required on create: Yes
Example:
"Newsletter Subscribers"
The tag name as it appears within your Envoke account.
group
Type: String
Read-only: No — updatable via PATCH.
Required on create: No
Accepted values (write): Group name (string) or group ID (integer). The group must be of type
interest.Returned value (read): The group name as a string. Returns
""(empty string) when no group is assigned.Example:
"Member Programs",""
Pass "" (empty string) or null to remove an existing group assignment via PATCH.
description
Type: String
Read-only: No — updatable via PATCH.
Required on create: No
Example:
"Members interested in our annual trade conference"
An internal description visible only to account administrators. Not shown to contacts.
display_names
Type: Object
Read-only: No — updatable via PATCH.
Required on create: No
Format:
{ "<language_code>": "<display_text>" }Example:
{ "en": "Organic Certification", "fr": "Certification biologique" }
Translated display labels for the tag, keyed by ISO language code. Used where tags are displayed publicly (such as on website subscription forms). A value of "" means no translation has been set for that language. All enabled account languages are included as keys even if no translation exists.
Error Responses
Validation errors (missing required fields, invalid values):
{ "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'name' is required" ] } }Not-found behaviour varies by method:
GET
/tags/{id}— when the ID is not found, returns an empty array ([]).PATCH
/tags/{id}— when the ID is not found, returns a validation error:
{ "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Item with id '999999' not found"] } }DELETE
/tags/{id}— when the ID is not found, returns a validation error (same shape as PATCH above).
For code examples and interactive testing, visit api.envoke.com.