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

# List contacts

> Lists contacts, newest first, with cursor pagination.

Requires the `contacts:read` scope.




## OpenAPI

````yaml /openapi.yaml get /contacts
openapi: 3.1.0
info:
  title: Watx API
  version: '1'
  description: |
    The Watx public REST API. Send WhatsApp messages, manage contacts and
    segments, read conversations and messages, launch broadcasts, and register
    webhook endpoints.

    Every request authenticates with a workspace API key sent as a bearer
    token. A key acts on exactly one workspace and can only do what its scopes
    allow. Each operation below names the scope it requires.
  contact:
    name: Watx support
    email: support@watx.in
servers:
  - url: https://api.watx.in/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Account
    description: Check which workspace a key belongs to and what it can do.
  - name: Messages
    description: Send a WhatsApp message to a phone number.
  - name: Contacts
    description: Create, read, update and list contacts.
  - name: Conversations
    description: Read conversations and their messages.
  - name: Broadcasts
    description: Launch a template broadcast and follow its progress.
  - name: Segments
    description: Named audiences — static lists and saved filters.
  - name: Webhooks
    description: Register endpoints that receive events from your workspace.
paths:
  /contacts:
    get:
      tags:
        - Contacts
      summary: List contacts
      description: |
        Lists contacts, newest first, with cursor pagination.

        Requires the `contacts:read` scope.
      operationId: listContacts
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - name: search
          in: query
          description: |
            Matches the contact's name or phone number, case-insensitively.
            Characters other than letters, digits, space and `+ @ . - _` are
            stripped before the search runs.
          schema:
            type: string
          example: priya
        - name: tag
          in: query
          description: Return only contacts carrying this tag id.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: A page of contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                  - id: 7e2d9c01-55b4-4a3d-9c8e-0f1a2b3c4d5e
                    phone: '+919876543210'
                    instagram_username: null
                    channels:
                      - whatsapp
                    name: Priya Nair
                    email: priya@example.com
                    company: Acme Traders
                    avatar_url: null
                    tags:
                      - id: 1b2c3d4e-5f60-4712-8293-a4b5c6d7e8f9
                        name: vip
                        color: '#3b82f6'
                    created_at: '2026-09-01T09:12:44.000Z'
                    updated_at: '2026-09-10T11:02:10.000Z'
                meta:
                  next_cursor: MjAyNi0wOS0wMVQwOToxMjo0NC4wMDBafDdlMmQ5YzAx
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    limit:
      name: limit
      in: query
      description: Page size. Default 50, maximum 100. An unusable value falls back to 50.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    cursor:
      name: cursor
      in: query
      description: |
        The `meta.next_cursor` from the previous page, passed back verbatim. An
        unreadable cursor is ignored and the first page is returned.
      schema:
        type: string
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        phone:
          type:
            - string
            - 'null'
          description: |
            E.164 phone number. `null` for a contact who only exists on
            Instagram — check `channels` before assuming a string.
        instagram_username:
          type:
            - string
            - 'null'
          description: Public @handle. Display only; handles change.
        channels:
          type: array
          description: The platforms this contact is reachable on.
          items:
            type: string
            enum:
              - whatsapp
              - instagram
        name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        company:
          type:
            - string
            - 'null'
        avatar_url:
          type:
            - string
            - 'null'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ListMeta:
      type: object
      description: Pagination metadata on list responses.
      properties:
        next_cursor:
          type:
            - string
            - 'null'
          description: |
            Pass back as `?cursor=` for the next page. `null` means this was the
            last page.
    Tag:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        color:
          type: string
          description: Hex colour, for example `#3b82f6`.
    Error:
      type: object
      description: |
        Every failure uses this shape. Branch on `error.code`, which is stable;
        `error.message` is written for people and may be reworded.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: |
                One of `bad_request`, `invalid_request`, `unauthorized`,
                `forbidden`, `not_found`, `rate_limited`, `internal`, or a
                domain code such as `whatsapp_not_configured`, `meta_error`,
                `template_malformed`, `plan_limit_reached`,
                `subscription_lapsed`.
              example: bad_request
            message:
              type: string
              example: '''phone'' is required'
  responses:
    Unauthorized:
      description: |
        The key is missing, malformed, unknown, revoked or expired. All four
        answer the same way.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Missing or invalid API key
    Forbidden:
      description: The key is valid but was not granted the scope this operation requires.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: This API key is missing the 'messages:send' scope
    RateLimited:
      description: |
        More than 120 requests in a minute for this key. `Retry-After` says how
        many seconds to wait.
      headers:
        Retry-After:
          description: Seconds until the window resets.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per window.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left in this window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix time in seconds when the window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded for this API key
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |
        Your workspace API key, created in **Settings → API keys**, sent as
        `Authorization: Bearer <key>`. New keys start with `watx_live_`; keys
        issued before the rename start with `converse360_live_` and still work.

````