Tag API - Read | Envoke Help Center

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.
`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 100,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": "Water Rights Advocacy",
     "group": "Policy & Advocacy",
     "description": "Contacts who opted in to the monthly newsletter",
     "display_names": { "en": "", "fr": "" }
   } 
]

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": "Water Rights Advocacy",
   "group": "Policy & Advocacy",
   "description": "Contacts who opted in to the monthly newsletter",
   "display_names": { "en": "", "fr": "" } 
}

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.

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