politicalcomms-com 10DLC Campaigns API

openapi: 3.2.0
info:
  title: Political Comms 10DLC Campaigns 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), Conversations (read inbound threads and reply inside them), Contact Lists (S3 import and analysis), Media Files, Organizations and hierarchy, Brands, Campaigns, Tracking Domains, 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. 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.'
  version: 1.4.1
  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: 10DLC Campaigns
  description: List 10DLC campaigns (carrier registrations) across your organization hierarchy.
paths:
  /campaigns:
    get:
      tags:
      - 10DLC Campaigns
      summary: List Campaigns
      description: List all campaigns. Filter by organization or brand.
      operationId: listCampaigns
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/BrandId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        brand_id:
                          type: string
                        brand_name:
                          type: string
                          description: 'The brand''s display name as registered: the DBA (doing business as) name when one was given, otherwise the legal name.'
                        org_id:
                          type: string
                        org_name:
                          type: string
                        campaign_status:
                          type: string
                        notes:
                          type:
                          - string
                          - 'null'
                          maxLength: 100
                          description: Short internal note set in the dashboard. Never sent to the registrar or to recipients.
                        created_at:
                          type: string
                      additionalProperties: true
              example:
                success: true
                data:
                - id: camp_xyz789
                  name: Fall 2025 GOTV
                  brand_id: brand_abc123
                  brand_name: Smith PAC
                  org_id: org_123
                  org_name: Smith Campaign 2024
                  campaign_status: MNO_PROVISIONED
                  notes: GOTV texting
                  created_at: '2024-01-20T09:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /campaigns/{id}/throughput:
    get:
      tags:
      - 10DLC Campaigns
      summary: Get Campaign Throughput
      description: 'Carrier sending limits for a campaign''s brand and how much of today''s T-Mobile daily cap is used. The two carrier lanes are independent: `t_mobile` is present only once a T-Mobile daily cap has synced for the campaign, and `att` whenever the campaign has an AT&T rate on file, whatever the brand type (political brands included). Use it before scheduling to see how much room is left. Returns 404 `NOT_FOUND` when the campaign is outside the key''s scope. See Carrier throughput limits.'
      operationId: getCampaignThroughput
      parameters:
      - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      campaign_id:
                        type: string
                      brand_id:
                        type: string
                      carrier_metered:
                        type: boolean
                        description: true when at least one carrier lane applies to this campaign (`t_mobile` or `att` is present). false when both are null.
                      t_mobile:
                        type:
                        - object
                        - 'null'
                        description: T-Mobile per-brand daily message cap. null whenever the brand has no T-Mobile daily limit on file (political brands have none today), so when present `daily_cap` is always an integer. `used_today` and `remaining_today` are null when today's usage is temporarily unavailable; a null is never a zero.
                        properties:
                          daily_cap:
                            type: integer
                            description: Messages per day T-Mobile allows this brand.
                          used_today:
                            type:
                            - integer
                            - 'null'
                            description: Messages counted against the cap so far in the current Pacific day.
                          remaining_today:
                            type:
                            - integer
                            - 'null'
                            description: '`daily_cap` minus `used_today`, never below 0.'
                          pacific_day:
                            type: string
                            description: The current Pacific day (YYYY-MM-DD). The cap resets at midnight Pacific.
                      att:
                        type:
                        - object
                        - 'null'
                        description: AT&T per-minute limits for this campaign, counted in message parts. AT&T traffic is delivered at this rate; it never pauses a project and never slows other carriers. null only when the campaign has no AT&T rate on file. Every 10DLC campaign with a rate on file has its AT&T traffic delivered at it, whatever the brand type. The platform sends AT&T recipients right away and the carrier queue delivers them at this rate, usually within about an hour; only in the last 90 minutes of the recipients' sending window does the platform hold back AT&T recipients that could not be delivered before the window closes. Inside `att`, `sms_tpm` and `mms_tpm` are each null when that rate is not known.
                        properties:
                          sms_tpm:
                            type:
                            - integer
                            - 'null'
                            description: SMS message parts per minute. A text that splits into 2 or 3 parts counts 2 or 3 times.
                          mms_tpm:
                            type:
                            - integer
                            - 'null'
                            description: MMS messages per minute. A picture message counts once.
                    additionalProperties: true
                additionalProperties: true
              example:
                success: true
                data:
                  campaign_id: 4b8fa3c1-6d25-4e9a-bf47-8c2e5d9a3f71
                  brand_id: 7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64
                  carrier_metered: true
                  t_mobile:
                    daily_cap: 10000
                    used_today: 7250
                    remaining_today: 2750
                    pacific_day: '2026-09-28'
                  att:
                    sms_tpm: 4500
                    mms_tpm: 1200
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    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
              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
    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
    NotFound:
      description: Resource not found or not visible to this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Project not found
            code: PROJECT_NOT_FOUND
            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
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      description: Resource ID
      schema:
        type: string
    BrandId:
      name: brand_id
      in: query
      required: false
      description: Filter to a specific brand
      schema:
        type: string
    OrganizationId:
      name: organization_id
      in: query
      required: false
      description: Filter to a specific descendant organization
      schema:
        type: string
  schemas:
    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
    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).
    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.
  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.