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

# Get a contact list's metadata

> A list's metadata — how many contacts were kept and which rows were dropped, as recorded when the list was created. It is never recomputed after import, so it is not campaign progress. For the contacts themselves, page [`/contact-lists/{listId}/contacts`](/api-reference/contacts/page-through-a-lists-contacts).



## OpenAPI

````yaml /voice-agents/api-reference/openapi.yaml get /contact-lists/{listId}
openapi: 3.1.0
info:
  title: UpliftAI Voice Agents API
  version: '1.0'
  description: >-
    Build voice assistants, start conversations on the web or the phone, run
    calling campaigns, and receive outcomes by webhook. All endpoints take a
    bearer API key unless noted otherwise.
servers:
  - url: https://api.upliftai.org/v1
security:
  - apiKey: []
tags:
  - name: Assistants
  - name: Authoring an assistant
  - name: Starting a conversation
  - name: Sessions & call records
  - name: Campaigns
  - name: Campaign outcomes
  - name: Contacts
  - name: Google Sheet sources
  - name: Integrations & delivery health
paths:
  /contact-lists/{listId}:
    get:
      tags:
        - Contacts
      summary: Get a contact list's metadata
      description: >-
        A list's metadata — how many contacts were kept and which rows were
        dropped, as recorded when the list was created. It is never recomputed
        after import, so it is not campaign progress. For the contacts
        themselves, page
        [`/contact-lists/{listId}/contacts`](/api-reference/contacts/page-through-a-lists-contacts).
      operationId: getContactList
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: 894ab1c2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      responses:
        '200':
          description: The contact list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
              example:
                listId: 894ab1c2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                organizationId: a12b7e74-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                projectId: c782a4ec-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                name: Shifa Clinic patients — 19 August
                sourceKind: csv_upload
                summary:
                  willBeCalled: 3
                  excluded:
                    invalidPhone: 1
                    missingName: 0
                    duplicate: 1
                    dnc: 0
                    recentlyCalled: 0
                  errors:
                    - row: 5
                      issue: duplicate
                      value: '+923001234567'
                    - row: 6
                      issue: invalidPhone
                      value: '0300'
                contactCount: 3
                createdAt: '2026-08-18T05:17:55.237Z'
                updatedAt: '2026-08-18T05:17:55.237Z'
                version: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            No list with that id in the API key's project. A list in another
            project is invisible here, and a malformed id 404s rather than 400.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'Contact list not found: 00000000-0000-4000-8000-000000000000'
                error: Not Found
                statusCode: 404
components:
  schemas:
    ContactList:
      type: object
      properties:
        listId:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        projectId:
          type: string
          format: uuid
        name:
          type: string
        sourceKind:
          type: string
          enum:
            - csv_upload
            - paste
            - google_sheets
            - customer_api
        sourceRef:
          type: string
          description: >-
            Present only when the import supplied an `uploadId` or a sheet `ref`
            — inline rows have none, even when labelled `csv_upload`.
        summary:
          $ref: '#/components/schemas/ImportSummary'
        contactCount:
          type: integer
          description: Contacts stored — the same number as `summary.willBeCalled`.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          description: Equal to `createdAt`, since a list is never edited.
        version:
          type: integer
          description: Always `1`.
    Error:
      type: object
      properties:
        message:
          description: >-
            One message per failed field for validation errors, a single string
            otherwise.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        error:
          type: string
        statusCode:
          type: integer
    ImportSummary:
      type: object
      description: What the import kept and dropped.
      properties:
        willBeCalled:
          type: integer
          description: Rows that became contacts.
        excluded:
          type: object
          description: >-
            Dropped rows by reason. `dnc` and `recentlyCalled` are always `0` —
            those checks do not run yet.
          properties:
            invalidPhone:
              type: integer
            missingName:
              type: integer
            duplicate:
              type: integer
              description: >-
                Same number seen twice. Numbers are compared as E.164, so
                `03001234567` and `+923001234567` collapse to one contact,
                keeping the first spelling.
            dnc:
              type: integer
            recentlyCalled:
              type: integer
        errors:
          type: array
          description: The dropped rows, first 20 only.
          items:
            type: object
            properties:
              row:
                type: integer
                description: Line in the source file, counting the header as line 1.
              issue:
                type: string
                enum:
                  - invalidPhone
                  - missingName
                  - duplicate
                  - dnc
                  - recentlyCalled
              value:
                type: string
                description: >-
                  The row's phone number: raw source text for `invalidPhone` and
                  `missingName`, normalized for `duplicate`.
  responses:
    Unauthorized:
      description: A bearer key was sent but is not recognized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: invalid authorization
            error: Unauthorized
            statusCode: 401
    Forbidden:
      description: No API key sent, or the key lacks permission for this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Forbidden resource
            error: Forbidden
            statusCode: 403
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Project API key (`sk_api_…`).

````