> ## 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. Supports filtering by WhatsApp ID, customer association, and more. ## OpenAPI ````yaml /api/meta/whatsapp/openapi-whatsapp.yaml get /{phone_number_id}/contacts openapi: 3.1.0 info: title: Kapso Meta Proxy API version: 1.0.0 description: > Kapso's Meta Proxy API provides a unified interface to WhatsApp Business Platform with enhanced features and Kapso-specific extensions. This API acts as a proxy layer between your application and WhatsApp, adding: - Simplified authentication with project-level API keys - Enhanced message metadata and tracking - Conversation management capabilities - Voice call integration - Extended contact and template management ## Base URL All API requests are made to: `https://api.kapso.ai/meta/whatsapp/v24.0` ## Authentication The API supports authentication via **X-API-Key header** (recommended): ``` X-API-Key: your_project_api_key ``` Alternative: Bearer token authentication is also supported for backward compatibility: ``` Authorization: Bearer your_access_token ``` Note: X-API-Key is the recommended authentication method for the Meta Proxy API. contact: name: Kapso Support url: https://kapso.ai email: dev@kap.so servers: - url: https://api.kapso.ai/meta/whatsapp/v24.0 description: Production server security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Messages description: Send and retrieve WhatsApp messages - name: Conversations description: Manage WhatsApp conversations - name: Contacts description: Manage WhatsApp contacts - name: Templates description: Manage message templates - name: Media description: Upload and retrieve media files - name: Calls description: Manage voice calls - name: Settings description: Account settings and configuration - name: Business Profile description: Business profile management - name: Phone Numbers description: Phone number management - name: Flows description: WhatsApp Flow management (Beta) - name: Block Users description: Block and unblock WhatsApp users - name: Usernames description: Reserve and manage WhatsApp business usernames paths: /{phone_number_id}/contacts: parameters: - name: phone_number_id in: path required: true description: WhatsApp Business Phone Number ID schema: type: string example: '110987654321' get: tags: - Contacts summary: List contacts description: | Retrieve a paginated list of WhatsApp contacts for your project. Supports filtering by WhatsApp ID, customer association, and more. operationId: listContacts parameters: - name: wa_id in: query description: Filter by WhatsApp ID (phone number) schema: type: string example: '15551234567' - name: customer_id in: query description: Filter by associated customer ID schema: type: string example: cust_abc123 - name: has_customer in: query description: Filter by customer association (true/false) schema: type: boolean example: true - name: limit in: query description: Maximum number of results per page (default 20, max 100) schema: type: integer minimum: 1 maximum: 100 default: 20 - name: before in: query description: Cursor for previous page (Base64 encoded) schema: type: string - name: after in: query description: Cursor for next page (Base64 encoded) schema: type: string - name: fields in: query description: >- Filter response fields. Use `kapso()` to include Kapso-specific extensions. schema: type: string example: kapso() responses: '200': description: Successfully retrieved contacts content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/WhatsappContact' paging: $ref: '#/components/schemas/Paging' examples: success: summary: List of contacts value: data: - id: 123e4567-e89b-12d3-a456-426614174000 wa_id: '15551234567' profile_name: John Doe display_name: John (VIP Customer) metadata: customer_tier: premium tags: - vip - high-value created_at: '2024-01-10T08:00:00.000Z' updated_at: '2024-01-15T12:34:56.123Z' - id: 223e4567-e89b-12d3-a456-426614174001 wa_id: '15559876543' profile_name: Jane Smith display_name: null metadata: null created_at: '2024-01-12T10:00:00.000Z' updated_at: '2024-01-12T10:00:00.000Z' paging: cursors: after: >- eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xMlQxMDowMDowMC4wMDAwMDBaIiwiMjIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAxIl0sImNvbHVtbnMiOlsiY3JlYXRlZF9hdCIsImlkIl19 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: WhatsappContact: type: object required: - id properties: id: type: string description: Contact ID (UUID) example: 123e4567-e89b-12d3-a456-426614174000 wa_id: type: string nullable: true description: >- WhatsApp ID (phone number). Can be null when Meta only provides BSUID-based identity. example: '15551234567' business_scoped_user_id: type: string nullable: true description: WhatsApp business-scoped user ID example: US.13491208655302741918 parent_business_scoped_user_id: type: string nullable: true description: Parent business-scoped user ID when provided by Meta example: US.ENT.506847293015824 username: type: string nullable: true description: WhatsApp username when available example: '@testusername' profile_name: type: string description: WhatsApp profile name example: John Doe display_name: type: string description: Custom display name example: John (VIP Customer) metadata: type: object description: Custom metadata additionalProperties: true nullable: true created_at: type: string format: date-time description: Contact creation timestamp example: '2024-01-15T12:34:56.123Z' updated_at: type: string format: date-time description: Last update timestamp example: '2024-01-15T12:34:56.123Z' Paging: type: object properties: cursors: $ref: '#/components/schemas/PaginationCursor' Error: type: object required: - error properties: error: type: object required: - message - type - code properties: message: type: string description: Human-readable error message example: Invalid phone number format type: type: string description: Error category example: OAuthException code: type: integer description: Error code example: 400 error_subcode: type: integer description: More specific error code example: 1001 fbtrace_id: type: string description: Facebook trace ID for debugging example: AXk7s_8dR4eVHp9Kq2MmNlO PaginationCursor: type: object properties: before: type: string description: Cursor for previous page (Base64 encoded) example: >- eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNVQxMjozNDo1Ni4xMjM0NTZaIiwiMTIzNDUiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0= after: type: string description: Cursor for next page (Base64 encoded) example: >- eyJ2YWx1ZXMiOlsiMjAyNC0wMS0xNFQwOToyMTozMi43ODkwMTJaIiwiMTIzMjAiXSwiY29sdW1ucyI6WyJjcmVhdGVkX2F0IiwiaWQiXX0= securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: > Project API key for authentication. This is the recommended authentication method. Get your API key from the Kapso dashboard under Integrations > API keys. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | Bearer token authentication (alternative method). Note: X-API-Key authentication is recommended for the Meta Proxy API. ````