curl --request POST \
--url https://api.politicalcomms.com/v1/tags/{id}/contacts \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"identifiers": [
"+12025550141",
"voter@example.com"
]
}
'{
"success": true,
"data": {
"added": 2,
"invalid": 0
}
}Add Contacts to Tag
Put a manual tag on contacts. Send exactly one source: identifiers (up to 10,000 phone numbers or email addresses) or contact_list_id (everyone on a list). Identifiers that are neither a US phone number nor an email address are reported in invalid rather than failing the call. Identifiers are applied at once and the response carries counts. A contact list is tagged in the background: the call returns 202 with queued and job_id and no counts, and the tag’s member_count on GET /tags updates when the job finishes. An activity tag has no members and cannot be added to (400 TAG_NOT_MANUAL). Tagging a contact does not make it sendable: a tagged contact is only sent to through a list row the project’s sender can use.
Triggers send messages. If a live triggered project or email campaign listens for this tag (live_triggers on GET /tags), tagging a contact into it sends to that person. fire_triggers chooses whether it does: true by default with identifiers, false by default with contact_list_id. A synchronous response reports triggers.entered; a queued list echoes fire_triggers. Re-tagging a contact who already has the tag never fires it. Removing contacts takes no fire_triggers (400).
curl --request POST \
--url https://api.politicalcomms.com/v1/tags/{id}/contacts \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"identifiers": [
"+12025550141",
"voter@example.com"
]
}
'{
"success": true,
"data": {
"added": 2,
"invalid": 0
}
}Authorizations
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
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.
16 - 200Body
- Identifiers
- Contact list
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.
