> ## Documentation Index > Fetch the complete documentation index at: https://kapso-1adbad2d.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List WhatsApp contacts > Retrieve a paginated list of WhatsApp contacts for the project ## OpenAPI ````yaml api/legacy/openapi-whatsapp.yaml get /whatsapp_contacts openapi: 3.0.3 info: title: Kapso External API - WhatsApp API description: >- API for programmatically interacting with Kapso agents, executions, and WhatsApp conversations. This specification includes only WhatsApp API endpoints. version: 1.0.0 contact: name: Kapso Support servers: - url: https://app.kapso.ai/api/v1 description: Production server security: - ApiKeyAuth: [] paths: /whatsapp_contacts: get: tags: - WhatsApp Contacts summary: List WhatsApp contacts description: Retrieve a paginated list of WhatsApp contacts for the project operationId: listWhatsappContacts parameters: - name: page in: query description: Page number required: false schema: type: integer default: 1 - name: per_page in: query description: Items per page required: false schema: type: integer default: 20 - name: q[customer_id_eq] in: query description: Filter by exact customer ID match required: false schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 - name: q[customer_external_customer_id_eq] in: query description: Filter by customer's external ID from your system required: false schema: type: string example: CUS-12345 - name: q[customer_id_null] in: query description: Filter sandbox contacts (contacts with no customer assigned) required: false schema: type: boolean example: true - name: q[customer_id_not_null] in: query description: Filter contacts with customer assigned (non-sandbox) required: false schema: type: boolean example: true - name: q[profile_name_cont] in: query description: Filter by profile name contains (case insensitive partial match) required: false schema: type: string example: john - name: q[wa_id_cont] in: query description: Filter by phone number contains (partial match) required: false schema: type: string example: 555 - name: q[created_at_gteq] in: query description: Filter by created date greater than or equal to (ISO 8601 format) required: false schema: type: string format: date-time example: '2024-01-01T00:00:00.000Z' - name: q[created_at_lteq] in: query description: Filter by created date less than or equal to (ISO 8601 format) required: false schema: type: string format: date-time example: '2024-12-31T23:59:59.000Z' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/WhatsappContact' meta: $ref: '#/components/schemas/PaginationMeta' examples: all_contacts: summary: All contacts description: Returns all contacts when no filters are applied value: data: - id: contact-789ghi wa_id: '1234567890' profile_name: John Doe metadata: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' - id: contact-456def wa_id: '0987654321' profile_name: Jane Smith metadata: {} created_at: '2024-01-14T15:45:00Z' updated_at: '2024-01-14T15:45:00Z' meta: page: 1 per_page: 20 total_pages: 1 total_count: 2 customer_contacts: summary: Customer's contacts description: >- Returns contacts filtered by customer ID using q[customer_id_eq]=uuid value: data: - id: contact-789ghi wa_id: '1234567890' profile_name: John Doe metadata: customer_type: premium created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' meta: page: 1 per_page: 20 total_pages: 1 total_count: 1 sandbox_contacts: summary: Sandbox contacts description: >- Returns sandbox contacts (no customer) using q[customer_id_null]=true value: data: - id: contact-sandbox-123 wa_id: '5555555555' profile_name: Test User metadata: source: sandbox created_at: '2024-01-16T09:20:00Z' updated_at: '2024-01-16T09:20:00Z' meta: page: 1 per_page: 20 total_pages: 1 total_count: 1 name_search: summary: Name search description: >- Returns contacts matching profile name using q[profile_name_cont]=john value: data: - id: contact-789ghi wa_id: '1234567890' profile_name: John Doe metadata: {} created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' - id: contact-111aaa wa_id: '1111111111' profile_name: Johnny Smith metadata: {} created_at: '2024-01-13T11:15:00Z' updated_at: '2024-01-13T11:15:00Z' meta: page: 1 per_page: 20 total_pages: 1 total_count: 2 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] components: schemas: WhatsappContact: type: object properties: id: type: string format: uuid example: contact-789ghi wa_id: type: string example: '1234567890' description: The WhatsApp ID (normalized phone number) profile_name: type: string example: John Doe description: The contact's profile name from WhatsApp customer_id: type: string format: uuid nullable: true example: customer-456def description: ID of the associated customer, null for sandbox contacts metadata: type: object description: Additional metadata about the contact example: source: website tags: - lead - priority created_at: type: string format: date-time updated_at: type: string format: date-time PaginationMeta: type: object properties: page: type: integer example: 1 per_page: type: integer example: 20 total_pages: type: integer example: 5 total_count: type: integer example: 100 Error: type: object properties: error: type: string example: Resource not found status: type: integer example: 404 message: type: string example: The requested resource could not be found securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key required for all endpoints ````