Skip to main content
POST

Authorizations

X-API-Key
string
header
required

Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy. A key carries up to three permissions: public:read for GET requests, public:write for POST, PATCH, and PUT requests, and public:delete for DELETE requests. public:delete is only available together with public:write.

Headers

Idempotency-Key
string

Optional idempotency key: a unique string of 16-200 printable ASCII characters (a UUID is recommended). Retrying the write with the same key within 24 hours returns the stored response of the first call with an X-Idempotent-Replayed: true response header instead of executing it again. Reusing a key with a different request body returns 422 (IDEMPOTENCY_MISMATCH); a duplicate sent while the first call is still running returns 409 with a Retry-After header. Keys are scoped per endpoint and organization.

Required string length: 16 - 200

Body

application/json
name
string
required

The tag's name. Leading and trailing spaces are ignored. Names are not case sensitive: Donor and donor are the same tag, and the spelling stored first is kept.

Required string length: 1 - 64
identifiers
string[]
required

US phone numbers in any common format, or email addresses. Anything that is neither is counted in invalid.

Required array length: 1 - 10000 elements
Maximum string length: 320
organization_id
string<uuid>

A descendant organization to act in. Defaults to your key's own organization. An organization outside your key's reach returns a 403.

fire_triggers
boolean
default:true

Whether a contact who newly gets the tag is sent to through the live triggered projects and email campaigns that listen for this tag. Default true for identifiers. Tagging into a tag that has live_triggers (see GET /tags) MESSAGES people, so check it first and send false to tag without sending. The tag's member_count and the contacts' tags are the same either way.

Response

Contacts tagged, for the identifier source. The tag is in the response, and created says whether this call created it. A contact list source returns 202 instead.

success
boolean
required
data
object
required