> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatflows.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Customers

> Returns a list of your customers. You can search by name, phone or email, and filter by type, status, source, group or active state.

Results come in pages of 50 by default. Merged customers aren't included.


## OpenAPI

````yaml /api-collection/chatflows-api-v1.json get /api/v1/contacts
openapi: 3.1.0
info:
  title: ChatFlows REST API
  version: 1.0.0
  description: >-
    ChatFlows REST API (v1).


    **Base URL:** `https://app.chatflows.io/api/v1` — also shown, with a copy
    button, on your **Developer API Keys** page.


    **Auth:** every authenticated request sends `Authorization: Bearer <token>`,
    where the token is created under **Setup → Developer API Keys** in your
    dashboard.


    **What a token can see:** a token belongs to ONE workspace — your store's.
    Every endpoint returns only that workspace's data, and `/api/v1/account`
    describes your own workspace. A token created before tokens were tied to a
    workspace is refused with `401 token_not_scoped`; create a new one to
    replace it.


    **Scopes:** each endpoint's description lists the token ability it requires.
    Create your token with the matching scopes.


    **Pagination:** list endpoints return `{ data, links: { next, prev }, meta
    }`. Large/append-only collections (contacts, group members, webhooks) use
    opaque cursor pagination — follow `links.next` until it is `null`.
    `per_page` is clamped to 5–100.


    **Async sends:** message and OTP sends return `202` and are processed on the
    queue.


    **Error envelope:**

    ```json

    { "message": "...", "error_code": "...", "status": 4xx }

    ```


    **Modules:** Auth/Account · Channels · Contacts · Statuses · Sources ·
    Groups · Labels · Templates · Messages · Conversations · OTP.
servers:
  - url: https://app.chatflows.io
    description: ChatFlows
security:
  - bearerAuth: []
tags:
  - name: Root
    description: Unauthenticated service metadata.
  - name: Auth & Account
    description: Verify your token, and read workspace identity, plan and usage.
  - name: Channels
    description: Connected WhatsApp accounts and their phone numbers.
  - name: Customers
    description: Create, read, update, merge and bulk-manage customers.
  - name: Customer Statuses
    description: The pipeline statuses a contact can be assigned.
  - name: Customer Sources
    description: Where a contact originated (e.g. website, referral).
  - name: Customer Groups
    description: Named groups used to segment contacts and target campaigns.
  - name: Customer Labels
    description: Free-form labels for tagging contacts.
  - name: Templates
    description: WhatsApp message templates and their Meta approval status.
  - name: Messages
    description: Send template and free-form messages, and read delivery status.
  - name: Conversations
    description: Customer conversation threads and their message history.
  - name: OTP
    description: Send, verify and resend one-time passcodes over WhatsApp.
  - name: Error Examples
    description: Reference shapes for the errors any endpoint may return.
paths:
  /api/v1/contacts:
    get:
      tags:
        - Customers
      summary: List Customers
      operationId: contactsListContacts
      parameters:
        - name: search
          in: query
          schema:
            type: string
          description: Search by name, phone or email.
        - name: type
          in: query
          schema:
            type: string
            enum:
              - lead
              - customer
              - guest
          description: Only customers of this type.
        - name: contact_status_id
          in: query
          schema:
            type: integer
          description: Only customers with this customer status.
        - name: contact_source_id
          in: query
          schema:
            type: integer
          description: Only customers from this customer source.
        - name: group_id
          in: query
          schema:
            type: integer
          description: Only customers in this customer group.
        - name: is_active
          in: query
          schema:
            type: boolean
          description: '`true` for active customers only, `false` for inactive only.'
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: Page number.
        - name: per_page
          in: query
          schema:
            type: integer
            default: 50
            minimum: 5
            maximum: 100
          description: Customers per page, from 5 to 100.
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The customer's ID.
                        first_name:
                          type: string
                          description: First name.
                        last_name:
                          type: string
                          description: Last name.
                        display_name:
                          type: string
                          description: The name shown in your inbox.
                        phone:
                          type: string
                          description: >-
                            Phone number with country code, for example
                            `919876543210`. A leading `+` is allowed. Must be
                            unique in your workspace.
                        email:
                          type: string
                          description: Email address.
                        type:
                          type: string
                          description: '`lead`, `customer` or `guest`. Defaults to `lead`.'
                        is_active:
                          type: boolean
                          description: '`false` to mark the customer inactive.'
                        contact_status_id:
                          type: integer
                          description: >-
                            A customer status ID. If empty, your default status
                            is used.
                        contact_source_id:
                          type: integer
                          description: >-
                            A customer source ID. If empty, your first source is
                            used.
                        group_ids:
                          type: array
                          items:
                            type: integer
                          description: Customer group IDs this customer belongs to.
                        label_ids:
                          type: array
                          items:
                            type: integer
                          description: Customer tag IDs on this customer.
                        custom_fields:
                          type: object
                          properties:
                            company:
                              type: string
                          description: Values for your customer fields.
                        created_at:
                          type: string
                          description: When the customer was created.
                        updated_at:
                          type: string
                          description: When the customer was last changed.
                  links:
                    type: object
                    properties:
                      next: {}
                      prev: {}
                  meta:
                    type: object
                    properties:
                      per_page:
                        type: integer
                      current_page:
                        type: integer
                      last_page:
                        type: integer
                      total:
                        type: integer
              examples:
                200 OK:
                  summary: 200 OK
                  value:
                    data:
                      - id: 1
                        first_name: Jane
                        last_name: Doe
                        display_name: Jane Doe
                        phone: '+919876543210'
                        email: jane@example.com
                        type: lead
                        is_active: true
                        contact_status_id: 1
                        contact_source_id: 1
                        group_ids:
                          - 1
                        label_ids:
                          - 1
                        custom_fields:
                          company: Acme
                        created_at: '2026-06-26T10:00:00+00:00'
                        updated_at: '2026-06-26T10:00:00+00:00'
                    links:
                      next: null
                      prev: null
                    meta:
                      per_page: 50
                      current_page: 1
                      last_page: 1
                      total: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/QuotaExhausted'
      security:
        - bearerAuth:
            - contacts:read
components:
  responses:
    Unauthorized:
      description: >-
        Missing, invalid or expired API token — or an older token that is not
        tied to a workspace (`token_not_scoped`), in which case create a new one
        on the Developer API Keys page.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Missing API token.
            error_code: unauthenticated
            status: 401
    PaymentRequired:
      description: >-
        Your workspace has no active subscription, or its first payment is still
        pending.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Subscription required or expired.
            error_code: subscription_required
            status: 402
    Forbidden:
      description: >-
        The token lacks the required scope, or the account is suspended or on
        hold.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: 'This token is missing the required scope: contacts:write.'
            error_code: insufficient_scope
            status: 403
    QuotaExhausted:
      description: The monthly API request quota for the workspace is exhausted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: API request quota exhausted for this billing period.
            error_code: quota_exhausted
            status: 429
      headers:
        RateLimit-Limit:
          schema:
            type: integer
          description: Your API request quota for the current billing period.
        RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining in the current billing period.
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until the quota resets.
  schemas:
    Error:
      type: object
      description: Standard error envelope returned by every endpoint.
      properties:
        message:
          type: string
          description: Human-readable explanation.
        error_code:
          type: string
          description: Stable machine-readable code — branch on this, not the message.
        status:
          type: integer
          description: HTTP status code.
      required:
        - message
        - error_code
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your API key. Create one under **Setup → Developer API Keys** and select
        the permissions this endpoint needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.