Tag API - Fields Reference

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
id	string	Yes	—	Unique identifier assigned on creation.
external_id	string	Yes	—	Externally visible identifier used in public-facing integrations.
name	string	No	Yes	The tag name.
group	string	No	No	Group the tag belongs to. Empty string ("") when unassigned.
description	string	No	No	Internal description of the tag.
display_names	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).

---

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.