> ## Documentation Index > Fetch the complete documentation index at: https://docs.inbox.adraa.ai/llms.txt > Use this file to discover all available pages before exploring further. # List contacts > Lists everyone who has messaged the workspace, one row per contact, newest activity first. Mirrors the console's Contacts page: the same search, country, channel, assignment, and open-conversation filters, plus facet counts for building filter UIs. Contacts are created automatically when a customer first messages the workspace — they cannot be created or deleted through the API. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/contacts openapi: 3.1.0 info: title: Adraa Inbox API description: >- Public REST API for Adraa Inbox. Assign agents to conversations and send messages from your own systems. Authenticate every request with a workspace API token. version: 1.0.0 contact: email: support@adraa.ai servers: - url: https://api.inbox.adraa.ai description: Production security: - apiToken: [] paths: /api/v1/contacts: get: summary: List contacts description: >- Lists everyone who has messaged the workspace, one row per contact, newest activity first. Mirrors the console's Contacts page: the same search, country, channel, assignment, and open-conversation filters, plus facet counts for building filter UIs. Contacts are created automatically when a customer first messages the workspace — they cannot be created or deleted through the API. operationId: listContacts parameters: - name: search in: query description: Matches against the contact's name, email, and phone. schema: type: string maxLength: 160 example: sara - name: country in: query description: >- ISO-3166 alpha-2 country code, derived from the contact's phone number. Use the `facets.countries` of an unfiltered request to see which codes are present. schema: type: string minLength: 2 maxLength: 2 example: SA - name: channel in: query description: Only contacts who have a conversation on this channel. schema: type: string enum: - web - whatsapp - facebook - telegram - sms - email - name: assignment in: query description: >- `assigned` — the contact's latest conversation has an agent; `unassigned` — it does not. schema: type: string enum: - assigned - unassigned - name: hasOpen in: query description: When `true`, only contacts with at least one open conversation. schema: type: boolean - name: page in: query description: 1-based page number. Clamped to the last page when out of range. schema: type: integer minimum: 1 default: 1 - name: pageSize in: query description: Contacts per page. schema: type: integer minimum: 1 maximum: 100 default: 20 - name: sort in: query description: >- `activity` (default) is the page-based, last-activity order. `created` switches to a lightweight, cursor-paginated, newest-first listing by the contact's first appearance in the workspace — for polling new contacts. schema: type: string enum: - activity - created default: activity - name: cursor in: query description: >- Used only with `sort=created`: the `nextCursor` from the previous page. schema: type: string - name: limit in: query description: 'Used only with `sort=created`: page size (1–100).' schema: type: integer minimum: 1 maximum: 100 default: 50 responses: '200': description: One page of contacts plus facet counts content: application/json: schema: type: object properties: contacts: type: array items: $ref: '#/components/schemas/Contact' total: type: integer description: Contacts matching the filters, across all pages. example: 124 page: type: integer example: 1 pageSize: type: integer example: 20 totalPages: type: integer example: 7 facets: type: object description: >- Counts across the whole directory (unfiltered), for building filter dropdowns. properties: countries: type: array items: type: object properties: code: type: string example: SA count: type: integer example: 80 channels: type: array items: type: object properties: platform: type: string example: whatsapp count: type: integer example: 95 '401': $ref: '#/components/responses/Unauthorized' components: schemas: Contact: type: object properties: id: type: string description: Contact ID. example: cmbxgy7kq0002ph01u2v3w4x5 name: type: string description: >- Display name — the contact's name, or their phone/email when no name is known. example: Sara Al-Harbi email: type: - string - 'null' description: >- Email address, when known. `null` for contacts who only messaged via WhatsApp. example: sara@example.com phone: type: - string - 'null' description: E.164 phone number, when known. example: '+966501234567' countryIso: type: - string - 'null' description: ISO-3166 alpha-2 country code derived from the phone number. example: SA channels: type: array description: Channels this contact has conversations on. items: type: string enum: - web - whatsapp - facebook - telegram - sms - email example: - whatsapp - web conversationId: type: - string - 'null' description: >- The contact's most recently active conversation — use it to assign or message them. example: cmbxgz9pq0003ph01m4n5o6p7 conversationCount: type: integer example: 3 openCount: type: integer description: Conversations that are not closed. example: 1 lastActivityAt: type: - string - 'null' format: date-time example: '2026-06-12T10:30:00.000Z' assignedAgent: type: - object - 'null' description: Agent assigned to the contact's latest conversation. properties: id: type: string example: cmbxgwq1e0000ph01i0j1k2l3 nickname: type: string example: sara Error: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable explanation. details: description: Field-level details for validation errors. type: array items: type: object properties: field: type: string message: type: string responses: Unauthorized: description: Missing, invalid, or revoked API token content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_API_TOKEN message: Invalid or revoked API token securitySchemes: apiToken: type: http scheme: bearer description: >- Workspace API token created in Settings → API. Tokens start with `adraa_`. ````