> ## Documentation Index > Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt > Use this file to discover all available pages before exploring further. # List contacts > Retrieve a paginated list of WhatsApp contacts for your project. ## OpenAPI ````yaml /api/platform/v1/openapi-platform.yaml get /whatsapp/contacts openapi: 3.1.0 info: title: Kapso Platform API version: 0.2.0 description: > Build WhatsApp messaging into your product. Manage customers, connect phone numbers, send broadcasts, and handle conversations. servers: - url: https://api.kapso.ai/platform/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Manage customer accounts - name: Setup Links description: WhatsApp onboarding via embedded signup - name: Phone Numbers description: Connect and manage WhatsApp numbers - name: Webhooks description: Subscribe to WhatsApp events - name: Display Names description: Update WhatsApp business display names - name: Broadcasts description: | Send template messages at scale **Alpha**: This API is in alpha and subject to change - name: Conversations description: Manage conversation state - name: Media description: Upload media files for WhatsApp messaging - name: Users description: Manage project team members - name: Inbox Embeds description: Create and manage embeddable inbox access links - name: Webhook Deliveries description: View webhook delivery attempts and their status - name: External API Logs description: View logs of external API calls made by the project - name: Provider Models description: List available AI provider models - name: WhatsApp Flows description: Build interactive WhatsApp Flows for surveys and forms - name: Contacts description: Manage WhatsApp contacts paths: /whatsapp/contacts: get: tags: - Contacts summary: List contacts description: Retrieve a paginated list of WhatsApp contacts for your project. operationId: listWhatsappContactsPlatform parameters: - name: customer_id in: query description: Filter by associated customer ID schema: type: string - name: customer_external_id in: query description: Filter by customer external ID schema: type: string - name: has_customer in: query description: Filter by customer association (true/false) schema: type: boolean - name: profile_name_contains in: query description: Filter by profile name (case-insensitive substring match) schema: type: string - name: wa_id_contains in: query description: Filter by WhatsApp ID (substring match) schema: type: string - name: business_scoped_user_id in: query description: Filter by exact WhatsApp business-scoped user ID schema: type: string - name: created_after in: query description: Filter contacts created after this ISO 8601 timestamp schema: type: string format: date-time - name: created_before in: query description: Filter contacts created before this ISO 8601 timestamp schema: type: string format: date-time - name: page in: query description: > Page number for legacy offset pagination. Deprecated — use cursor pagination (`limit`, `after`, `before`) instead. Maximum page: 50. Maximum window (`page` × `per_page`): 5,000. Requests exceeding these limits return a 400 error. deprecated: true schema: type: integer default: 1 maximum: 50 - name: per_page in: query description: Items per page for legacy offset pagination. schema: type: integer default: 20 maximum: 100 - name: limit in: query description: >- Maximum number of results per cursor-paginated page (default 20, max 100). schema: type: integer minimum: 1 maximum: 100 default: 20 - name: before in: query description: Cursor for the previous page (Base64 encoded). schema: type: string - name: after in: query description: Cursor for the next page (Base64 encoded). schema: type: string responses: '200': description: Successfully retrieved contacts headers: X-Total: description: Present only for legacy offset pagination responses. schema: type: string X-Total-Pages: description: Present only for legacy offset pagination responses. schema: type: string X-Per-Page: description: Present only for legacy offset pagination responses. schema: type: string X-Page: description: Present only for legacy offset pagination responses. schema: type: string Link: description: >- RFC 5988 pagination links for legacy offset pagination responses. schema: type: string content: application/json: schema: $ref: '#/components/schemas/WhatsappContactListResponse' examples: offsetPagination: value: data: - id: 123e4567-e89b-12d3-a456-426614174000 wa_id: '15551234567' profile_name: John Doe display_name: John (VIP) customer_id: 550e8400-e29b-41d4-a716-446655440000 metadata: segment: vip created_at: '2025-03-26T15:05:00.000000Z' updated_at: '2025-03-26T15:05:00.000000Z' - id: 223e4567-e89b-12d3-a456-426614174001 wa_id: '15557654321' profile_name: Jane Smith display_name: null customer_id: null metadata: source: sandbox created_at: '2025-03-26T15:00:00.000000Z' updated_at: '2025-03-26T15:00:00.000000Z' meta: page: 1 per_page: 20 total_pages: 1 total_count: 2 cursorPagination: value: data: - id: 123e4567-e89b-12d3-a456-426614174000 wa_id: '15551234567' profile_name: John Doe display_name: John (VIP) customer_id: 550e8400-e29b-41d4-a716-446655440000 metadata: segment: vip created_at: '2025-03-26T15:05:00.000000Z' updated_at: '2025-03-26T15:05:00.000000Z' - id: 223e4567-e89b-12d3-a456-426614174001 wa_id: '15557654321' profile_name: Jane Smith display_name: null customer_id: null metadata: source: sandbox created_at: '2025-03-26T15:00:00.000000Z' updated_at: '2025-03-26T15:00:00.000000Z' paging: cursors: before: >- eyJ2YWx1ZXMiOlsiMjAyNS0wMy0yNlQxNTowNTowMC4wMDAwMDBaIiwiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIl0sImNvbHVtbnMiOlsiY3JlYXRlZF9hdCIsImlkIl19 after: >- eyJ2YWx1ZXMiOlsiMjAyNS0wMy0yNlQxNTowMDowMC4wMDAwMDBaIiwiMjIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAxIl0sImNvbHVtbnMiOlsiY3JlYXRlZF9hdCIsImlkIl19 next: >- eyJ2YWx1ZXMiOlsiMjAyNS0wMy0yNlQxNTowMDowMC4wMDAwMDBaIiwiMjIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAxIl0sImNvbHVtbnMiOlsiY3JlYXRlZF9hdCIsImlkIl19 previous: null '400': description: Legacy pagination limit exceeded content: application/json: schema: type: object properties: message: type: string example: legacy_offset_pagination_limit_exceeded detail: type: string example: >- Page 51 exceeds the maximum supported legacy offset page (50). Use cursor pagination with limit, after, and before. requested_page: type: integer example: 51 requested_per_page: type: integer example: 100 requested_window: type: integer example: 5100 max_page: type: integer example: 50 max_window: type: integer example: 5000 cursor_example: type: string example: >- https://api.kapso.ai/platform/v1/whatsapp/contacts?limit=100 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: WhatsappContactListResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/WhatsappContact' meta: $ref: '#/components/schemas/PaginationMeta' paging: $ref: '#/components/schemas/Paging' ErrorResponse: type: object required: - error properties: error: type: string WhatsappContact: type: object properties: id: type: string format: uuid description: Unique contact ID example: 123e4567-e89b-12d3-a456-426614174000 wa_id: type: - string - 'null' description: >- WhatsApp ID (E.164 phone number). Can be null when Meta only provides BSUID-based identity. example: '15551234567' business_scoped_user_id: type: - string - 'null' description: WhatsApp business-scoped user ID example: US.13491208655302741918 parent_business_scoped_user_id: type: - string - 'null' description: Parent business-scoped user ID when provided by Meta example: US.ENT.506847293015824 username: type: - string - 'null' description: WhatsApp username when available example: '@testusername' profile_name: type: string description: Name as shown on WhatsApp example: John Doe display_name: type: string nullable: true description: Custom display name set by your app example: John (VIP) customer_id: type: string format: uuid nullable: true description: Associated customer ID metadata: type: object nullable: true additionalProperties: true description: Custom key-value data created_at: type: string format: date-time updated_at: type: string format: date-time PaginationMeta: type: object required: - page - per_page - total_pages - total_count properties: page: type: integer minimum: 1 per_page: type: integer minimum: 1 total_pages: type: integer minimum: 0 total_count: type: integer minimum: 0 Paging: type: object properties: cursors: $ref: '#/components/schemas/PaginationCursor' next: type: string nullable: true previous: type: string nullable: true PaginationCursor: type: object properties: before: type: string description: Cursor for previous page (Base64 encoded) after: type: string description: Cursor for next page (Base64 encoded) securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````