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

# Get Contact List

> Fetch a single contact list including import progress and analysis results.



## OpenAPI

````yaml /api-reference/openapi.json get /contact-lists/{id}
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), 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 Keys 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 100 requests per hour per key.


    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.0.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
servers:
  - url: https://api.politicalcomms.com/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Organizations
    description: List descendant organizations and hierarchy.
  - name: Brands
    description: List brands across your organization hierarchy.
  - name: Campaigns
    description: List campaigns across your organization hierarchy.
  - name: Tracking Domains
    description: >-
      List active link-tracking domains. Use the returned ids as
      `link_tracking_domain_id` on project create/update.
  - 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: Contact Lists
    description: List, import, and analyze contact lists.
  - name: Media Files
    description: List, import, and fetch media files.
  - name: Projects
    description: Create, edit, test, schedule, and inspect projects.
  - name: Analytics
    description: Message statistics and delivery performance.
  - name: Billing
    description: Usage and billing data across your organization.
paths:
  /contact-lists/{id}:
    get:
      tags:
        - Contact Lists
      summary: Get Contact List
      description: >-
        Fetch a single contact list including import progress and analysis
        results.
      operationId: getContactList
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                success: true
                data:
                  id: cl_abc123
                  list_name: Spring Outreach List
                  org_id: org_123
                  brand_id: brand_abc123
                  status: ready
                  contact_count: 12500
                  import_progress:
                    rows_total: 12500
                    rows_imported: 12500
                    rows_skipped: 0
                  analysis:
                    mobile: 11200
                    landline: 800
                    voip: 350
                    invalid: 150
                    last_run_at: '2025-03-15T10:05:00Z'
                  created_at: '2025-03-15T10:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      description: Resource ID
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          example:
            success: false
            error: The provided API key is invalid or has been revoked
            code: INVALID_API_KEY
            statusCode: 401
    NotFound:
      description: Resource does not exist
      content:
        application/json:
          example:
            success: false
            error: Resource not found
            code: NOT_FOUND
            statusCode: 404
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          description: Maximum requests allowed in the current window
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests remaining in the current window
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp (seconds) when the limit resets
          schema:
            type: integer
      content:
        application/json:
          example:
            success: false
            error: >-
              Rate limit exceeded. Try again after the X-RateLimit-Reset
              timestamp.
            code: RATE_LIMIT_EXCEEDED
            statusCode: 429
  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.

````