List all tags

get

https://{youraccountname}.api-us1.com/api/3/tags

Returns tag definitions, each with subscriber_count, the number of contacts the tag is applied to. Contact tags are returned by default; pass type=template for template tags. To find a tag by exact name, use filters[tag] or filters[search][eq]; both match the whole name, ignoring case. For a partial-name search, use search: it is a case-insensitive substring match, so it returns every similarly named tag alongside the one asked for. Identify the tag you want by comparing the tag field of each result, never by its position in the list. To apply a tag to a contact, pass the returned id to POST /contactTags. Unrecognized filter and order parameters are silently ignored. When that happens the response contains the unfiltered set with the unfiltered total, so a request with a misspelled filter looks successful while returning every tag. Soft-deleted tags are never listed. Results are sorted by id ascending unless order, selected_tag_id or orders[search]=weight applies; orders[tag], orders[type] and orders[id] have no effect. meta.total is the number of tags that matched, returned as a string; when counting is slow it can come from a cache of up to five minutes. The list is read from a replica, so a tag created a moment ago can be missing briefly.

{
    "tags": [
        {
            "tagType": "contact",
            "tag": "one",
            "description": "",
            "cdate": "2018-08-17T09:43:15-05:00",
            "links": {
                "contactGoalTags": "https://:account.api-us1.com/api/:version/tags/1/contactGoalTags"
            },
            "id": "1"
        },
        {
            "tagType": "contact",
            "tag": "two",
            "description": "",
            "cdate": "2018-08-17T13:41:16-05:00",
            "links": {
                "contactGoalTags": "https://:account.api-us1.com/api/:version/tags/2/contactGoalTags"
            },
            "id": "2"
        },
        {
            "tagType": "contact",
            "tag": "three",
            "description": "",
            "cdate": "2018-08-17T13:41:18-05:00",
            "links": {
                "contactGoalTags": "https://:account.api-us1.com/api/:version/tags/3/contactGoalTags"
            },
            "id": "3"
        },
        {
            "tagType": "template",
            "tag": "test1",
            "description": "",
            "cdate": "2018-08-28T11:54:36-05:00",
            "links": {
                "contactGoalTags": "https://:account.api-us1.com/api/:version/tags/4/contactGoalTags"
            },
            "id": "4"
        },
        {
            "tagType": "template",
            "tag": "test2",
            "description": "",
            "cdate": "2018-08-28T11:54:38-05:00",
            "links": {
                "contactGoalTags": "https://:account.api-us1.com/api/:version/tags/5/contactGoalTags"
            },
            "id": "5"
        }
    ],
    "meta": {
        "total": "5"
    }
}

Query Params

string

Filters tags by name. Partial matches are included (a contains match), within the selected type only. If both search and filters[search] are sent, search wins and filters[search] is ignored. The characters % and _ in the value act as SQL wildcards, and a value of 0 is ignored.

filters[tag]

string

Filters by exact tag name. The simplest way to look up one tag by name. Names are unique within a type, so at most one tag matches.

exact_tag

string

Exact tag name; the same as filters[tag].

tags[]

array of strings

Array form, tags[]=a&tags[]=b: returns the tags whose name is exactly one of the values, within the selected type. A single tags=value without brackets is ignored.

tags[]

type

string

enum

Selects which tag type the response contains: contact (the default) or template. Any other value is treated as contact. Every response contains only one type of tag. Sending filters[type] instead of this parameter does not work and can return an empty result.

Allowed:

filters[search][<operator>]

string

Filters tags by name using the operator. Supported operators: eq (exact name match), neq, lt, lte, gt, gte, contains, starts_with. Send only one operator per request: when several are sent, the last value is applied to every operator. in is not supported here and returns an empty list, as does any other operator value.

filters[id][<operator>]

string

Filters by tag id. Supported operators: eq, neq, lt, lte, gt, gte, and in with a comma-separated list of ids (for example filters[id][in]=1,2,3). Always send an operator: filters[id]=1 without one is a contains match on the digits, so it also returns ids such as 10 and 21.

ids

string

Comma-separated list of tag ids to return, or the array form ids[]=1&ids[]=2. Overrides limit. Only tags of the selected type are returned, so ids of template tags need type=template.

orders[search]

string

enum

Sorts search results by relevance: exact matches first, then tags starting with the searched text, then the rest. weight is the only supported value, and it only applies when filters[search] is also sent and the legacy order parameter is absent. Ordering by other fields is not supported; any other orders parameter is silently ignored and the default sort by id applies.

Allowed:

order

string

enum

Legacy sort. popular orders by subscriber_count, highest first, and adds a count field to each tag (for type=template, count is the number of templates using the tag, reported as 1 for a tag no template uses); alpha orders by name, A to Z. Overrides the default id order and orders[search]=weight. Any other value leaves the list in no particular order.

Allowed:

direction

string

enum

Sort direction for order. Defaults to desc for popular and asc for alpha; ignored without order.

Allowed:

selected_tag_id

string

Tag id, or array of ids, to place at the top of the list ahead of the normal ordering. Tags the filters exclude are not added.

template_in_use

string

When present with any value, returns only tags applied to at least one template. Meant for type=template.

include_automation_status

integer

1 adds has_automation to every tag in the response: true when a visible automation has a tag added or tag removed trigger for the tag, an add or remove tag action naming it, or a segment condition on the tag in its start or actions. It runs several extra queries per tag, so use a small limit.

include

string

Comma-separated related collections to add to the response: contactGoalTags, templateTags. Unknown names are ignored. GET /tags/{id} ignores this parameter.

limit

integer

Number of results to return. Default 20. Values above 100 are capped to 100; the literal value null raises the cap to 1000 for that request.

offset

integer

Number of results to skip. Use with limit to page through results.

Response

Language

Credentials

Header

URL

Loading…

Response

Choose an example:

application/json

200The tags that matched, one type per response.