> ## 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. # Page through a list's contacts > The rows as they were saved when the list was created, not a fresh read of the source file or sheet. `q` filters after each page is read, so a page can come back empty while later pages still hold matches — keep going until `nextCursor` is absent. Pages are ordered by `contactId` as text rather than import order, and there is no sort parameter. ## OpenAPI ````yaml /voice-agents/api-reference/openapi.yaml get /contact-lists/{listId}/contacts 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}/contacts: get: tags: - Contacts summary: Page through a list's contacts description: >- The rows as they were saved when the list was created, not a fresh read of the source file or sheet. `q` filters after each page is read, so a page can come back empty while later pages still hold matches — keep going until `nextCursor` is absent. Pages are ordered by `contactId` as text rather than import order, and there is no sort parameter. operationId: listContactListContacts parameters: - name: listId in: path required: true schema: type: string format: uuid example: 134ccad1-xxxx-xxxx-xxxx-xxxxxxxxxxxx - name: q in: query required: false description: >- Case-insensitive substring match on `name` and `phone`. Values in `attributes` are not searched. schema: type: string example: ayesha - name: limit in: query required: false description: >- Rows read per page. Values above 100 are clamped to 100; anything non-numeric or below 1 falls back to 50 instead of erroring. schema: type: integer default: 50 example: 2 - name: cursor in: query required: false description: The previous page's `nextCursor`. Opaque — do not construct one. schema: type: string responses: '200': description: >- One page, ordered by `contactId` as text rather than import order, so `+92…` rows come before `03…` ones. There is no sort parameter. content: application/json: schema: $ref: '#/components/schemas/ContactPage' examples: firstPage: summary: First page of a five-contact list, `?limit=2` value: contacts: - listId: 134ccad1-xxxx-xxxx-xxxx-xxxxxxxxxxxx contactId: '+923001234567' organizationId: a12b7e74-xxxx-xxxx-xxxx-xxxxxxxxxxxx projectId: c782a4ec-xxxx-xxxx-xxxx-xxxxxxxxxxxx name: Ayesha Siddiqui phone: '+923001234567' attributes: Doctor: Dr Imran Shaikh AppointmentTime: کل صبح 11 بجے - listId: 134ccad1-xxxx-xxxx-xxxx-xxxxxxxxxxxx contactId: '+923009876543' organizationId: a12b7e74-xxxx-xxxx-xxxx-xxxxxxxxxxxx projectId: c782a4ec-xxxx-xxxx-xxxx-xxxxxxxxxxxx name: Hamza Raza phone: '+923009876543' attributes: Doctor: Dr Sana Tariq AppointmentTime: کل شام 5 بجے nextCursor: >- eyJjb250YWN0SWQiOiIrOTIzMDA5ODc2NTQzIiwibGlzdElkIjoiMTM0Y2NhZDEteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4In0 filteredPageWithNoMatches: summary: >- `?q=zainab&limit=1` — the row read on this page did not match, but Zainab is on a later one value: contacts: [] nextCursor: >- eyJjb250YWN0SWQiOiIrOTIzMDAxMjM0NTY3IiwibGlzdElkIjoiMTM0Y2NhZDEteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4In0 '400': description: The `cursor` was not one this API issued. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid pagination cursor error: Bad Request statusCode: 400 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- No such list in the API key's project. A list in another project returns the same 404, not a 403. 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: ContactPage: type: object properties: contacts: type: array items: $ref: '#/components/schemas/Contact' nextCursor: type: string description: >- Pass back as `cursor` to read the next page. Absent on the last page. 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 Contact: type: object properties: listId: type: string format: uuid contactId: type: string description: >- The contact's phone number. Contacts are deduplicated on it within a list. organizationId: type: string format: uuid projectId: type: string format: uuid name: type: string description: Who the assistant addresses on the call. phone: type: string description: >- The number to dial, same value as `contactId`. Kept in the format it was imported in — `+923001234567` and `03001234567` are both stored as given. attributes: type: object additionalProperties: type: string description: >- The imported row's remaining columns, under their original headers. On a campaign dial they are appended to the assistant's instructions as a contact record — there is no `{{placeholder}}` substitution. 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_…`). ````