List all contact-tag associations

List the tags applied to contacts. Each item is a single contact-to-tag association, and its id is the value to pass to DELETE /contactTags/{id} when removing a tag from a contact.

Filter by contact, by tag, or by both to look up a specific association. Note that the filters use the underlying column names subscriberid and tagid, while the response returns the same values as contact and tag — filters[contact] and filters[tag] are not supported.

Unrecognized filter and order parameters are silently ignored, so a request with a misspelled filter looks successful while returning the unfiltered set.

Associations whose tag has since been deleted are still listed here and counted in meta.total; GET /tags/{id} for such a tag returns 404. The contact's own listing, GET /contacts/{id}/contactTags, hides them.

To get the contacts that carry a tag, rather than the association rows, use GET /contacts with tagid, or filters[tagName] for a tag name.

filters[cdate] matches one exact timestamp, not a day or a range. To answer "which contacts got tag X since a date", filter by filters[tagid], order with orders[cdate]=desc and stop paging when cdate passes the date.

No permission beyond API access is checked, so any API user can list every association in the account, including contacts that are not on their lists. Associations whose contact no longer exists are left out.

Query Params
int32

Filter by the id of the contact the tag is applied to. This is the same value the response returns as contact.

int32

Filter by the id of the tag. This is the same value the response returns as tag.

date-time

Return only associations applied at exactly this date and time, written YYYY-MM-DD HH:MM:SS in the platform timezone, the one the response's other timestamps carry. This is an exact match: a date without a time matches nothing, and there is no range form. To find the tags applied since a date, filter by filters[tagid], order with orders[cdate]=desc and page until cdate passes the date. An operator suffix such as filters[cdate][gt] is applied as an exact match with that value, not as a range.

string
enum

Order results by the date the tag was applied to the contact.

Allowed:
string
enum

Order results by tag id, ascending or descending.

Allowed:
string
enum

Order results by contact id, ascending or descending.

Allowed:
string

Comma-separated list of contactTag association ids to return. Overrides limit; offset still applies.

int32
Defaults to 20

The number of records to return for each call. Default is 20; maximum value is 100.

int32
Defaults to 0

Offset index of records to return.

Responses

403

The request has no valid API token. The body is empty.

Language
Credentials
Header
URL
LoadingLoading…
Response
Choose an example:
application/json