Tag API - Read

Use the read endpoints to retrieve tags for your account. You can list all tags with filtering and sorting, or retrieve a single tag by ID.

---

Endpoints

Method	URL	Description
GET	https://e1.envoke.com/v2/tags	Return a list of tags.
GET	https://e1.envoke.com/v2/tags/{ID}	Return a single tag.

Authentication is via HTTP Basic Auth using your API ID and API Key.

---

List Tags

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

Returns a JSON array of tags for your account, sorted alphabetically by name by default. Supports filtering, sorting, pagination, and field selection.

Query Parameters

Parameter	Type	Default	Description
limit	integer	10	Maximum number of results to return. Hard cap is 100 unless ?fields= or ?result_type=kvp is also set (see note below).
skip	integer	0	Number of records to skip. Use with limit to paginate.
fields	string	(all)	Comma-separated list of fields to include in each result. See limit note below.
result_type	string	(array)	Set to kvp to receive results as a key-value object ({ "id": "name" }). See limit note below.
filter[id]	string	—	Filter by tag ID.
filter[name]	string	—	Filter by tag name. Matches the whole name. A space and an underscore are different characters here, unlike in the Contact API’s interests. Whether letter case is ignored is not guaranteed, so send the name with the capitalisation it was created with. Can return more than one tag, because names are not unique.
filter[external_id]	string	—	Filter by external ID.
filter[group]	string	—	Filter by group name.
filter[description]	string	—	Filter by description.
sort[name]	string	—	Sort by name. Value: asc or desc.

Note — limit behaviour with ?fields= and ?result_type=kvp: When either of these parameters is present, the default limit increases to 10,000 (returning all records if no explicit limit is specified) and a ?limit= value above 100 is honoured as-is. This allows full exports and dropdown population without pagination.

Filter Operators

All filter[field] parameters support exact match and the not-equal operator:

Operator	Example	Description
(none)	?filter[name]=Newsletter	Exact match
(ne)	?filter[group][(ne)]=Archived	Not equal

Note: URL-encode brackets in production requests (e.g. %5B for [).

Response

A JSON array of tag objects. Returns an empty array ([]) if no tags exist or no results match the filter.

[
  {
    "id": "42",
    "external_id": "a1b2c3d4e5f6",
    "name": "Newsletter Subscribers",
    "group": "Engagement",
    "description": "Contacts who opted in to the monthly newsletter",
    "display_names": { "en": "Newsletter", "fr": "Infolettre" }
  }
]

display_names is always present in list responses.

---

Get a Single Tag

GET https://e1.envoke.com/v2/tags/{ID}

Returns a single tag object. Replace {ID} with the Envoke tag ID.

If the ID is not found, the API returns an empty array ([]).

Response

{
  "id": "42",
  "external_id": "a1b2c3d4e5f6",
  "name": "Newsletter Subscribers",
  "group": "Engagement",
  "description": "Contacts who opted in to the monthly newsletter",
  "display_names": { "en": "Newsletter", "fr": "Infolettre" }
}

---

Examples

Return all tags (default pagination)

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags"

Paginate through results

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?limit=10&skip=10"

Filter by group

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?filter%5Bgroup%5D=Member+Programs"

Filter by name

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?filter%5Bname%5D=Newsletter+Subscribers"

Filter excluding a group

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?filter%5Bgroup%5D%5B%28ne%29%5D=Archived"

Sort by name descending

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?sort%5Bname%5D=desc"

Return only specific fields

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?fields=id,name,group"

Return as a key-value map (for dropdowns)

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?result_type=kvp"

Response:

{ "42": "Newsletter Subscribers", "43": "Event Attendees" }

Get a single tag by ID

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags/42"

---

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