Tag API - Insert

Use this endpoint to create a new tag in your account.

---

Endpoint

POST https://e1.envoke.com/v2/tags

Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

Request Body

Field	Type	Required	Description
name	string	Yes	The tag name.
group	string or integer	No	Group name or group ID to assign the tag to. The group must be of type interest.
description	string	No	Internal description of the tag.
display_names	object	No	Translated display labels keyed by ISO language code (e.g. { "en": "...", "fr": "..." }).

---

Response

On success, the API returns the newly created tag object:

{
  "success": true,
  "result_text": "Created",
  "result_data": {
    "id": "42",
    "external_id": "a1b2c3d4e5f6",
    "name": "Newsletter Subscribers",
    "group": "Engagement",
    "description": "Contacts who opted in to the monthly newsletter",
    "display_names": { "en": "Newsletter" }
  }
}

result_data.id is the Envoke tag ID. Store this if you need to update, delete, or assign contacts to the tag later.

---

Validation Errors

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "The field 'name' is required"
    ]
  }
}

Common validation errors:

Error	Cause
Request body may not be empty	No JSON body was provided.
The field 'name' is required	name was missing or blank.
Invalid 'group': '{value}'	The group name or ID was not found, or is not of type interest.

---

Examples

Create a basic tag

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter Subscribers"}' \
  "https://e1.envoke.com/v2/tags"

Create with a group and description

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Annual Conference Attendees", "group": "Events", "description": "Members who attend our annual conference"}' \
  "https://e1.envoke.com/v2/tags"

Create with translated display names

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter Subscribers", "display_names": {"en": "Newsletter", "fr": "Infolettre"}}' \
  "https://e1.envoke.com/v2/tags"

---

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

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