curl --request POST \
--url https://api.politicalcomms.com/v1/tags/contacts \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"name": "Door knockers",
"identifiers": [
"+12025550141",
"voter@example.com"
]
}
'{
"success": true,
"data": {
"tag": {
"id": "5b1f3c2e-7a94-4d08-8e61-2c9d4f7a1b35",
"name": "Door knockers",
"kind": "manual",
"activity_event": null,
"within_days": null,
"member_count": 2,
"member_count_capped": false,
"created_at": "2026-11-17T14:02:11.000Z",
"organization_id": "9d2e6a40-1c73-4b58-a0f9-3e8b5c7d2a16"
},
"created": true,
"added": 2,
"invalid": 0
}
}Add Contacts to Tag by Name
Put a manual tag on contacts by the tag’s name, in one call. You do not need to create the tag first: if the organization has no tag with this name, it is created, and created in the response is true. Check created to notice a misspelled name that made a new tag. Names are not case sensitive. Send the name and 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. The tag is still created immediately. A name always means a tag you can add contacts to: one that matches an activity’s generated name (such as Clicked) makes a tag of that name beside it. Projects and email campaigns still refer to tags by id (tag_ids, require_tag_ids, suppression_tag_ids): use tag.id from the response or GET /tags. 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/contacts \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"name": "Door knockers",
"identifiers": [
"+12025550141",
"voter@example.com"
]
}
'{
"success": true,
"data": {
"tag": {
"id": "5b1f3c2e-7a94-4d08-8e61-2c9d4f7a1b35",
"name": "Door knockers",
"kind": "manual",
"activity_event": null,
"within_days": null,
"member_count": 2,
"member_count_capped": false,
"created_at": "2026-11-17T14:02:11.000Z",
"organization_id": "9d2e6a40-1c73-4b58-a0f9-3e8b5c7d2a16"
},
"created": true,
"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.
