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

# List contacts

> Filters combine: the contact must match every filter sent. All of them apply only to the
contacts of the token's company.

Text filters match part of the value, ignoring case. An empty filter is ignored; a repeated
filter (`?email=a&email=b`) returns `422` (`ERR_API_VALIDATION`).



## OpenAPI

````yaml /api-reference/openapi.en.yaml get /contacts
openapi: 3.0.3
info:
  title: Connecta DESK Public API
  version: 1.0.0
  description: >-
    Public API of Connecta DESK, available at `/api/v1`. Access uses a token
    generated in the tokens module. Each token has permissions per **module ×
    method**, and every list read is paginated.


    ## Authentication


    ```

    Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

    ```


    The token belongs to a **company**, not to a user. The company used is
    always the token's company, so sending `companyId` in the body has no
    effect. A missing, invalid, revoked or expired token gets the same `401`
    response.


    ## Order of checks


    1. **token** → `401`

    2. **active company** → `403`

    3. **API enabled on the plan** → `403 ERR_API_NOT_ENABLED` (does not apply
    to on-premise)

    4. **company rate limit** → `429`

    5. **token permission** → `403 ERR_API_FORBIDDEN_SCOPE`


    ## User ids


    Every user id in the API is the user's id **in this company**, the same one
    `GET /users` returns. This applies to what the API returns (`user.id`,
    `assignedTo.id`, `userCreated.id`) and to what it accepts (`userId`,
    `userIds`, `assignedToUserId` and the `{id}` in user routes).


    The same person can work in several companies, with a different name and
    profile in each one, and has a different id in each company.


    An id that does not belong to this company returns `404`, with the same
    message as an id that does not exist.


    ## Pagination


    Every list `GET` is paginated. The `meta` contains only `page`, `perPage`
    and `hasMore`, without the total number of records. To go through
    everything, keep advancing `page` while `hasMore` is `true`.


    ## Idempotency


    Optional on `POST`/`PUT`, through the `Idempotency-Key` header. If you
    repeat the call with the same key and the same body, you get the stored
    response (with `Idempotent-Replay: true`). With the same key and a different
    body, the response is `409`.
servers:
  - url: https://api.connectadesk.com/api/v1
    description: Production
security:
  - apiToken: []
tags:
  - name: contacts
    description: Contact records, extra fields and marketing source.
  - name: tickets
    x-displayName: Tickets
    description: Opening, transferring, closing and wrap-up of tickets.
  - name: messages
    description: Asynchronous sending and reading of messages.
  - name: tags
    description: Tags and their link to tickets.
  - name: queues
    description: Service queues and their agents.
  - name: wrapups
    description: Wrap-up types.
  - name: users
    description: Agents and administrators.
  - name: schedules
    description: Scheduled messages.
  - name: quick-messages
    description: Quick replies.
  - name: campaigns
    description: Bulk sending.
  - name: crm
    description: Boards, stages, cards and metrics.
  - name: channels
    description: Channels (read only).
  - name: reports
    description: Reports and dashboards.
  - name: products
    description: Product catalog, categories and sales performance.
  - name: custom-fields
    description: Custom fields for contacts and cards, plus company-wide global variables.
  - name: profiles
    description: Company permission profiles (read only).
  - name: webchat
    description: >-
      Native webchat from your own system: open a visitor session, send and read
      messages. The token needs the `webchat` scope (GET and POST).
paths:
  /contacts:
    get:
      tags:
        - contacts
      summary: List contacts
      description: >-
        Filters combine: the contact must match every filter sent. All of them
        apply only to the

        contacts of the token's company.


        Text filters match part of the value, ignoring case. An empty filter is
        ignored; a repeated

        filter (`?email=a&email=b`) returns `422` (`ERR_API_VALIDATION`).
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/perPage'
        - name: search
          in: query
          description: >-
            Free search by name, number, code or LID. A digits-only term also
            finds the contact by id.
          schema:
            type: string
          example: marina
        - name: tagsIds
          in: query
          description: >-
            Tag ids, separated by commas. Returns the contacts that have a
            ticket with any of these tags. A tag that is not from your company
            returns `422` (`ERR_API_INVALID_REFERENCE`).
          schema:
            type: string
          example: 3,7
        - name: channelsIds
          in: query
          description: >-
            Channel ids, separated by commas. Returns the contacts whose last
            conversation channel is one of these. A channel that is not from
            your company returns `422` (`ERR_API_INVALID_REFERENCE`).
          schema:
            type: string
          example: '4'
        - name: name
          in: query
          description: Filters by name.
          schema:
            type: string
          example: Marina
        - name: number
          in: query
          description: >-
            Filters by phone number. Only the digits are compared: `+55 (11)
            99999` is the same as `5511999999`. Without any digit, returns
            `422`.
          schema:
            type: string
          example: '5511999999999'
        - name: email
          in: query
          description: Filters by email.
          schema:
            type: string
          example: marina@exemplo.com.br
        - name: code
          in: query
          description: Filters by the contact's code in your system.
          schema:
            type: string
          example: CLI-8842
        - name: origin
          in: query
          description: Filters by origin.
          schema:
            type: string
          example: Site
        - name: cpfCnpj
          in: query
          description: Filters by CPF or CNPJ.
          schema:
            type: string
          example: '12345678909'
        - name: lid
          in: query
          description: Filters by the WhatsApp LID.
          schema:
            type: string
          example: '178452961234567'
        - name: instagramUsername
          in: query
          description: Filters by Instagram username. The `@` is optional.
          schema:
            type: string
          example: marina.alves
        - name: sourceUrl
          in: query
          description: Marketing — filters by the source page.
          schema:
            type: string
          example: https://exemplo.com.br/promo
        - name: sourceId
          in: query
          description: Marketing — filters by the source id (e.g. the ad id).
          schema:
            type: string
          example: '120210000000000'
        - name: headline
          in: query
          description: Marketing — filters by the ad headline.
          schema:
            type: string
          example: Matrículas abertas
        - name: mediaType
          in: query
          description: Marketing — filters by the source media type.
          schema:
            type: string
          example: image
        - name: mediaUrl
          in: query
          description: Marketing — filters by the source media URL.
          schema:
            type: string
          example: https://exemplo.com.br/banner.jpg
        - name: utmSource
          in: query
          description: Marketing — filters by `utm_source`.
          schema:
            type: string
          example: google
        - name: utmMedium
          in: query
          description: Marketing — filters by `utm_medium`.
          schema:
            type: string
          example: cpc
        - name: utmCampaign
          in: query
          description: Marketing — filters by `utm_campaign`.
          schema:
            type: string
          example: setembro
        - name: utmId
          in: query
          description: Marketing — filters by `utm_id`.
          schema:
            type: string
          example: abc123
        - name: fbclid
          in: query
          description: Marketing — filters by `fbclid` (click on a Meta ad).
          schema:
            type: string
          example: IwAR0abc
        - name: gclid
          in: query
          description: Marketing — filters by `gclid` (click on a Google ad).
          schema:
            type: string
          example: Cj0KCQjw
        - name: ctwaClid
          in: query
          description: >-
            Marketing — filters by `ctwa_clid` (click on a Click to WhatsApp
            ad).
          schema:
            type: string
          example: ARAkLk
        - name: customFields
          in: query
          style: deepObject
          explode: true
          description: >-
            Filters by a contact custom field, in the format
            `customFields[<key>]=<value>` — the

            `key` is the same one returned by `GET
            /custom-fields?application=contact` and in each

            contact's `customFields` list. You can send several fields; the
            contact must match all of them.


            Text, long text, email, phone and link fields match part of the
            value. The others (number,

            currency, date, select and yes/no) require the exact value — dates
            in the `DD/MM/YYYY`

            format.


            A `key` that is not a contact field of your company returns `422`

            (`ERR_API_INVALID_REFERENCE`); a value that does not match the field
            type, `422`

            (`ERR_API_VALIDATION`).
          schema:
            type: object
            additionalProperties:
              type: string
          example:
            cargo_do_contato: diretor
            data_de_aniversario: 15/03/1994
        - name: from
          in: query
          description: >-
            Returns contacts created on or after this date, in the company's
            time zone.
          schema:
            type: string
            format: date
          example: '2026-09-01'
        - name: to
          in: query
          description: >-
            Returns contacts created up to this date, in the company's time
            zone.
          schema:
            type: string
            format: date
          example: '2026-09-30'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  meta:
                    $ref: '#/components/schemas/PageMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    page:
      name: page
      in: query
      description: Page number, starting at 1. An invalid value is treated as 1.
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    perPage:
      name: perPage
      in: query
      description: >-
        Number of items per page. The maximum depends on the environment
        (default 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 50
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Display name.
        number:
          type: string
        numberCountry:
          type: string
          nullable: true
          description: >-
            Country of the number, as an ISO 3166-1 alpha-2 code. Inferred from
            the country code when the number is saved through the API.
          example: BR
        email:
          type: string
          nullable: true
          example: marina@exemplo.com.br
        code:
          type: string
          nullable: true
        cpfCnpj:
          type: string
          nullable: true
          example: '12345678909'
        origin:
          type: string
          nullable: true
        profilePicUrl:
          type: string
          nullable: true
          example: https://cdn.exemplo.com.br/avatar/1042.jpg
        isGroup:
          type: boolean
          description: The contact is a group, not a person.
        instagramUsername:
          type: string
          nullable: true
          example: marina.alves
        lid:
          type: string
          nullable: true
          example: '178452961234567'
        sourceUrl:
          type: string
          nullable: true
          example: https://loja.exemplo.com.br/promo
        sourceId:
          type: string
          nullable: true
          example: '23851234567890123'
        headline:
          type: string
          nullable: true
          example: Coleção de inverno
        mediaType:
          type: string
          nullable: true
          example: image
        mediaUrl:
          type: string
          nullable: true
          example: https://cdn.exemplo.com.br/anuncios/inverno.jpg
        utmSource:
          type: string
          nullable: true
          example: instagram
        utmMedium:
          type: string
          nullable: true
          example: cpc
        utmCampaign:
          type: string
          nullable: true
          example: inverno-2026
        utmId:
          type: string
          nullable: true
          example: '6543210987'
        fbclid:
          type: string
          nullable: true
          example: IwAR0xYzAbC123
        gclid:
          type: string
          nullable: true
        ctwaClid:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
                description: Display name.
              color:
                type: string
                description: Color in hexadecimal, with `#`.
                example: '#6941C6'
        customFields:
          type: array
          description: >-
            Contact custom fields that are filled in. Always included in the
            response, as an empty list when the contact has none.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
        lastChannel:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
              description: Display name.
            type:
              type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      example:
        id: 842
        name: Maria Silva
        number: '5511987654321'
        numberCountry: BR
        email: maria.silva@exemplo.com.br
        code: CLI-00842
        cpfCnpj: '12345678909'
        origin: site
        profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg
        isGroup: false
        instagramUsername: maria.silva
        lid: null
        sourceUrl: https://loja.exemplo.com.br/promo
        sourceId: '23851234567890123'
        headline: Coleção de inverno
        mediaType: image
        mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg
        utmSource: instagram
        utmMedium: cpc
        utmCampaign: inverno-2026
        utmId: '6543210987'
        fbclid: IwAR0xYzAbC123
        gclid: null
        ctwaClid: null
        tags:
          - id: 3
            name: Cliente VIP
            color: '#6941C6'
        customFields:
          - key: plano
            value: Ouro
            customFieldId: 91
            name: Plano
            type: select
        lastChannel:
          id: 11
          name: Instagram Loja
          type: instagram
        createdAt: '2026-07-14T13:22:05.412Z'
        updatedAt: '2026-08-18T09:41:17.883Z'
    PageMeta:
      type: object
      required:
        - page
        - perPage
        - hasMore
      properties:
        page:
          type: integer
          example: 1
        perPage:
          type: integer
          example: 20
        hasMore:
          type: boolean
          description: Whether there are more records beyond this page.
          example: true
      example:
        page: 1
        perPage: 20
        hasMore: true
    CustomFieldValue:
      type: object
      description: >-
        Value of a custom field, together with the field's definition. This way
        you do not need to call `GET /custom-fields` to find out what field 91
        is.
      properties:
        key:
          type: string
          nullable: true
          description: >-
            Fixed identifier of the field. Use it to point to the field when
            saving values, because the `name` can be renamed in the panel and
            the integration would stop working without warning.
        value:
          type: string
          description: Value filled in for the field, in the format defined by its type.
        customFieldId:
          type: integer
          description: Id of the custom field definition.
          example: 91
        name:
          type: string
          nullable: true
          description: Display name.
        type:
          type: string
          nullable: true
          description: Field type, which defines the format accepted for the value.
      example:
        key: plano
        value: Ouro
        customFieldId: 91
        name: Plano
        type: select
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Fixed error code, so your system can handle each case.
              example: ERR_API_FORBIDDEN_SCOPE
            message:
              type: string
            details: {}
  responses:
    Unauthorized:
      description: Token missing, invalid, revoked or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_UNAUTHORIZED
              message: Token de API ausente ou inválido.
    Forbidden:
      description: >-
        Inactive company, API not enabled on the plan, or insufficient
        permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_FORBIDDEN_SCOPE
              message: >-
                O token não tem permissão para este método neste módulo. A
                mensagem real nomeia os dois.
    UnprocessableEntity:
      description: >-
        The body is well formed, but a required field is missing or a value is
        not accepted. For example, `application` other than `contact`/`card`, an
        empty `orderedIds` or a blank `name`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_VALIDATION
              message: >-
                O parâmetro `application` é obrigatório e aceita "contact" ou
                "card".
    TooManyRequests:
      description: The company exceeded its requests-per-minute limit.
      headers:
        RateLimit-Limit:
          schema:
            type: integer
          description: Requests-per-minute limit.
        RateLimit-Remaining:
          schema:
            type: integer
          description: How many requests are left in the current window.
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until the window resets.
        Retry-After:
          schema:
            type: integer
          description: How long to wait before trying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_API_RATE_LIMIT
              message: Limite de requisições por minuto excedido para esta empresa.
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: API token in the `sk_live_…` format.

````

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