> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`).



## OpenAPI

````yaml /api-reference/openapi.json post /tags/contacts
openapi: 3.1.0
info:
  title: Political Comms API
  summary: >-
    Direct-to-carrier political texting API for campaigns, PACs, advocacy
    organizations, fundraisers, and elected officials.
  description: >-
    Public REST API for the Political Comms platform. Surfaces include Projects
    (compose, test, schedule, send, and triggered projects that text each person
    a trigger brings in), Conversations (read inbound threads and reply inside
    them), Lists (one import for phone numbers and emails, and analysis), Media
    Files, Organizations and hierarchy, Brands, Campaigns, Tracking Domains,
    Webhook Endpoints, Phone Numbers, Analytics, and Billing.


    Authentication is an API key passed in the `X-API-Key` header. Keys are
    generated from the dashboard at Admin → API and are prefixed `pc_live_`. All
    POST and PATCH endpoints that mutate state are designed to be safe to retry,
    with optional `Idempotency-Key` headers for stronger guarantees. Rate limit
    is 600 requests per minute per key (bursts up to 600, refilling at 10 per
    second, the same for every scope; the `X-RateLimit-Limit` header reports
    your key's exact limit, and `Retry-After` on a 429 is the seconds until your
    next request is allowed).


    Webhooks emit `message.sent`, `message.delivered`, `message.failed`,
    `message.replied`, and `link.clicked` events, plus email events including
    `email.sent`, `email.failed` and `email.opened`. Payloads are HMAC-signed;
    validate the signature before trusting any payload.


    A Model Context Protocol (MCP) server is available at
    https://docs.politicalcomms.com/mcp for AI agents that need to search the
    documentation programmatically. The developer hub at
    https://politicalcomms.com/developers/ has quickstart examples in cURL, raw
    HTTP, and Python.


    Triggered projects and email campaigns have no contact list: each person is
    added when a trigger fires (a WinRed or Anedot donation, a link click or
    reply in another project or campaign, or an API call or inbound hook URL),
    and gets one message, immediately or after a delay.
  version: 1.14.0
  termsOfService: https://politicalcomms.com/terms/
  contact:
    name: Political Comms Support
    email: support@politicalcomms.com
    url: https://docs.politicalcomms.com
  license:
    name: Proprietary
    url: https://politicalcomms.com/terms/
  x-logo:
    url: https://politicalcomms.com/images/brand/pcomms-logo-left-of-text.png
    altText: Political Comms
    backgroundColor: '#ffffff'
    href: https://politicalcomms.com/
  x-mcp:
    url: https://docs.politicalcomms.com/mcp
    discovery_url: https://docs.politicalcomms.com/.well-known/mcp
    transport: http
    auth: none
    tools:
      - search_political_comms
      - query_docs_filesystem_political_comms
      - submit_feedback
servers:
  - url: https://api.politicalcomms.com/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Projects
    description: Create, edit, test, schedule, and inspect projects.
  - name: Conversations
    description: >-
      Read inbound threads and reply inside them from the same number.
      Conversations are created by project sends; the API never starts one.
  - name: Phone Numbers
    description: List phone numbers across 10DLC campaigns and toll-free verifications.
  - name: Toll-Free Verifications
    description: >-
      List toll-free verifications (carrier registrations) across your
      organization hierarchy.
  - name: Brands
    description: List brands across your organization hierarchy.
  - name: 10DLC Campaigns
    description: >-
      List 10DLC campaigns (carrier registrations) across your organization
      hierarchy.
  - name: Email Campaigns
    description: >-
      Create, schedule, and report on email campaigns. Pause, resume, and test
      sends are deliverability decisions a human makes while watching a send,
      and live in the dashboard.
  - name: Email Templates
    description: Create and read saved email templates.
  - name: Email Senders
    description: >-
      Read the sender identities (From addresses) on your verified domains.
      Identities carry the physical mailing address and paid-for-by disclaimer,
      so they are created and edited in the dashboard.
  - name: Email Suppressions
    description: >-
      Addresses that will not be emailed: unsubscribes, bounces, complaints, and
      addresses you add. Read, add, and lift them in bulk to keep your own
      opt-out record in sync with ours. They apply automatically to every email
      send.
  - name: Contact Lists
    description: >-
      List, import, and analyze lists. One import brings in phone numbers,
      emails, or both, or a do-not-contact file.
  - name: Tags
    description: >-
      Label contacts and send to the label. Manual tags have members you add and
      remove; activity tags (donated, clicked, responded, sent) apply by
      themselves. Send to tags with `tag_ids` on projects and email campaigns.
  - name: Media Files
    description: List, import, and fetch media files.
  - name: Sending Domains
    description: >-
      Read the sending domains in your organization and the DNS records to
      publish. Domains are added in the dashboard: DNS is published by hand, so
      creation is not part of the API.
  - name: Tracking Domains
    description: >-
      List active link-tracking domains. Use the returned ids as
      `link_tracking_domain_id` on project create/update.
  - name: Webhook Endpoints
    description: >-
      Read your webhook endpoints and whether deliveries to them are failing.
      Endpoints are created, edited and re-enabled in the dashboard, where the
      signing secret is shown.
  - name: Organizations
    description: List descendant organizations and hierarchy.
  - name: Billing
    description: Usage and billing data across your organization.
  - name: Analytics
    description: Message statistics and delivery performance.
paths:
  /tags/contacts:
    post:
      tags:
        - Tags
      summary: Add Contacts to Tag by Name
      description: >-
        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`).
      operationId: addTagContactsByName
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  title: Identifiers
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 64
                      description: >-
                        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.
                    identifiers:
                      type: array
                      minItems: 1
                      maxItems: 10000
                      items:
                        type: string
                        maxLength: 320
                      description: >-
                        US phone numbers in any common format, or email
                        addresses. Anything that is neither is counted in
                        `invalid`.
                    organization_id:
                      type: string
                      format: uuid
                      description: >-
                        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:
                      type: boolean
                      default: true
                      description: >-
                        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.
                  required:
                    - name
                    - identifiers
                  additionalProperties: false
                - type: object
                  title: Contact list
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 64
                      description: >-
                        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.
                    contact_list_id:
                      type: string
                      format: uuid
                      description: >-
                        Every active phone number and every subscribed email
                        address on this list. The list must belong to the
                        organization; otherwise `404` `LIST_NOT_FOUND`.
                    organization_id:
                      type: string
                      format: uuid
                      description: >-
                        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:
                      type: boolean
                      default: false
                      description: >-
                        Whether the contacts newly tagged are sent to through
                        the live triggered projects and email campaigns that
                        listen for this tag. Default `false` for
                        `contact_list_id`: a whole list is tagged without
                        sending unless you ask. `true` messages everyone on the
                        list who did not already have the tag, so check
                        `live_triggers` on `GET /tags` and confirm first.
                  required:
                    - name
                    - contact_list_id
                  additionalProperties: false
            examples:
              identifiers:
                summary: Phone numbers and emails
                value:
                  name: Door knockers
                  identifiers:
                    - '+12025550141'
                    - voter@example.com
              list:
                summary: Everyone on a list
                value:
                  name: Door knockers
                  contact_list_id: 3f7a1c9e-5b2d-4e86-9a04-7c1d3f5e9b28
      responses:
        '200':
          description: >-
            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.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      tag:
                        $ref: '#/components/schemas/Tag'
                      created:
                        type: boolean
                        description: True only when this call created the tag.
                      added:
                        type: integer
                        description: Contacts newly tagged.
                      invalid:
                        type: integer
                        description: >-
                          Identifiers that were neither a US phone number nor an
                          email address. Always 0 for a contact list.
                      triggers:
                        type: object
                        description: >-
                          Present only when a live triggered project or campaign
                          listens for this tag: how many contacts were entered
                          into them. 0 when `fire_triggers` was false.
                        properties:
                          entered:
                            type: integer
                        required:
                          - entered
                        additionalProperties: true
                    required:
                      - tag
                      - created
                      - added
                      - invalid
                    additionalProperties: true
                required:
                  - success
                  - data
                additionalProperties: true
              example:
                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
        '202':
          description: >-
            Contact list source: queued. Everyone on the list is being tagged in
            the background, and the tag is created now if it did not exist.
            `added` and `invalid` are not returned. `tag.member_count` is the
            count before the job runs; the new count shows on `GET /tags` once
            it finishes. Replaying the same `Idempotency-Key` returns this
            response and queues nothing new.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      tag:
                        $ref: '#/components/schemas/Tag'
                      created:
                        type: boolean
                        description: True only when this call created the tag.
                      queued:
                        type: boolean
                        description: >-
                          Always true. The work was accepted and runs in the
                          background.
                      job_id:
                        type: string
                        description: >-
                          Identifies the background job, for your own records.
                          There is no endpoint to poll it: read `member_count`
                          on `GET /tags` after it finishes.
                      fire_triggers:
                        type: boolean
                        description: >-
                          Echoes whether the job fires the tag's live triggers
                          for the people it newly tags.
                    required:
                      - tag
                      - created
                      - queued
                      - job_id
                    additionalProperties: true
                required:
                  - success
                  - data
                additionalProperties: true
              example:
                success: true
                data:
                  tag:
                    id: 5b1f3c2e-7a94-4d08-8e61-2c9d4f7a1b35
                    name: Door knockers
                    kind: manual
                    activity_event: null
                    within_days: null
                    member_count: 0
                    member_count_capped: false
                    created_at: '2026-11-17T14:02:11.000Z'
                    organization_id: 9d2e6a40-1c73-4b58-a0f9-3e8b5c7d2a16
                  created: true
                  queued: true
                  job_id: 5c0e8a7d-3b14-4f2a-9d65-1e7b0c4a8f39
        '400':
          description: >-
            Validation failure: no name, no source or two sources, or more than
            10,000 identifiers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Validation failed
                code: VALIDATION_ERROR
                correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            `contact_list_id` is not a list of the organization
            (`LIST_NOT_FOUND`). No tag is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Contact list not found
                code: LIST_NOT_FOUND
                correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
        '409':
          description: >-
            An import is writing the same contacts. Error code `TAG_BUSY`; retry
            in about a minute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  An import is still writing these contacts. Try again in a
                  minute.
                code: TAG_BUSY
                correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 16
        maxLength: 200
      description: >-
        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.
  schemas:
    Tag:
      type: object
      description: >-
        A label on contacts (phone numbers and email addresses) inside one
        organization. A `manual` tag has members you add and remove. An
        `activity` tag has no stored members: it applies by itself to everyone
        for whom the activity is true when a send is compiled.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            Unique within the organization, ignoring case. An activity tag is
            named by its activity (for example `Donated in the last 30 days`).
        kind:
          type: string
          enum:
            - manual
            - activity
        activity_event:
          type:
            - string
            - 'null'
          enum:
            - donated
            - clicked
            - responded
            - sent
            - null
          description: The activity an `activity` tag follows. Null on a manual tag.
        within_days:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 365
          description: >-
            For an activity tag, how many days back the activity counts. Null
            means any time. Always null on a manual tag.
        member_count:
          type:
            - integer
            - 'null'
          description: >-
            Members of a manual tag, counted up to 10,000 (see
            `member_count_capped`). Null on an activity tag, which has no stored
            members.
        member_count_capped:
          type: boolean
          description: >-
            True when a manual tag has more than 10,000 members and
            `member_count` stops at 10,000.
        live_triggers:
          type: array
          description: >-
            Only on the rows of `GET /tags`. The live triggered projects and
            email campaigns that listen for this tag (started, not ended or
            deleted); empty when none and always empty on an activity tag.
            Tagging a contact with this tag sends to that person, so read this
            before a bulk tag: see `fire_triggers` on `POST
            /tags/{id}/contacts`.
          items:
            type: object
            required:
              - id
              - name
              - channel
            properties:
              id:
                type: string
                format: uuid
                description: The triggered project's or email campaign's id.
              name:
                type: string
              channel:
                type: string
                enum:
                  - text
                  - email
            additionalProperties: true
        created_at:
          type: string
          format: date-time
        organization_id:
          type: string
          format: uuid
          description: The organization the tag belongs to.
      required:
        - id
        - name
        - kind
        - activity_event
        - within_days
        - member_count
        - member_count_capped
        - created_at
        - organization_id
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: >-
            Machine-readable error code, e.g. VALIDATION_ERROR,
            ORG_ACCESS_DENIED, PROJECT_NOT_FOUND.
        correlationId:
          type: string
          description: Request correlation ID; include it in support requests.
        details:
          type:
            - array
            - object
          description: >-
            Present on some errors. For VALIDATION_ERROR, an array of { field,
            message, code } with one entry per rejected field (field is the
            dotted path); an object for other codes (e.g. insufficient-balance
            shortfall).
      required:
        - error
        - code
      additionalProperties: true
      description: >-
        Standard error body produced by the API error handler for 4xx/5xx
        responses.
    AuthErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Short error summary.
        message:
          type: string
          description: Human-readable detail.
      required:
        - error
        - message
      additionalProperties: true
      description: >-
        Error body returned by the API-key authentication layer (401 and
        permission 403s).
    RateLimitErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
        message:
          type: string
        code:
          type: string
          enum:
            - RATE_LIMIT_EXCEEDED
        statusCode:
          type: integer
          enum:
            - 429
        retryAfter:
          type: integer
          description: >-
            Seconds until the rate-limit window resets. Also sent as the
            Retry-After header.
      required:
        - success
        - error
        - code
        - statusCode
        - retryAfter
      additionalProperties: true
  responses:
    Unauthorized:
      description: Missing, malformed, revoked, or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthErrorResponse'
          example:
            error: API key required
            message: Please provide an API key in the X-API-Key header
    Forbidden:
      description: >-
        The API key lacks the required permission scope, or the requested
        resource belongs to an organization outside the key's hierarchy.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/AuthErrorResponse'
              - $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingScope:
              summary: >-
                Key lacks the required permission scope (here a GET from a key
                without `public:read`)
              value:
                error: Insufficient permissions
                message: >-
                  This API key does not have the required permissions:
                  public:read
            orgAccessDenied:
              summary: Resource outside the key's organization hierarchy
              value:
                error: >-
                  Access denied: You do not have permission to access this
                  organization's data
                code: ORG_ACCESS_DENIED
                correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
    RateLimited:
      description: Rate limit exceeded. Check the Retry-After header.
      headers:
        Retry-After:
          description: Seconds until the window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
          example:
            success: false
            error: Rate limit exceeded
            message: Maximum 600 requests per 60 seconds
            code: RATE_LIMIT_EXCEEDED
            statusCode: 429
            retryAfter: 3
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: An unexpected error occurred. Please try again later.
            code: INTERNAL_ERROR
            correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        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`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.