Skip to main content

Tag API - Insert

Written by Marcus Warren

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.

For code examples and interactive testing, visit api.envoke.com.

Did this answer your question?