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

# Pesquisar contatos

> Encontre contatos com filtros avançados, grupos lógicos, paginação e ordenação.

**URL completa:** `https://services.leadconnectorhq.com/contacts/search`

> [!NOTE]
>
> **Token e permissões:** na Salez, acesse **Configurações > Integrações Privadas** para gerar ou gerenciar o token, conforme seu nível de acesso. Esta operação exige o escopo `contacts.readonly`. Envie `Authorization: Bearer <token>` e `Version: v3`. O filtro `filters` aceita comparações e agrupamentos `AND` e `OR`. Veja a [visão geral de Contatos](https://docs.salez.com.br/contatos/visao-geral.md).

## Como funcionam os filtros

O corpo da requisição recebe o identificador da subconta, a quantidade de registros e filtros opcionais. Em `filters`, cada item pode ser um **filtro de campo** ou um **grupo** `AND` / `OR` de filtros.

```json theme={"system"}
{
  "locationId": "<locationId>",
  "pageLimit": 20,
  "page": 1,
  "filters": [
    { "field": "city", "operator": "eq", "value": "São Paulo" },
    { "field": "tags", "operator": "eq", "value": "cliente" }
  ],
  "sort": [{ "field": "dateAdded", "direction": "desc" }]
}
```

Os filtros acima são combinados por `AND`, retornando contatos da cidade de São Paulo que também tenham a etiqueta `cliente`.

### Campos mais utilizados

| Tipo | Campos disponíveis | Operadores |
| - | - | - |
| Identificação | `id` | `eq`, `not_eq` |
| Nome | `contactName`, `firstNameLowerCase`, `lastNameLowerCase` | `eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists`\* |
| Contato e localização | `address`, `city`, `state`, `postalCode`, `phone`, `companyName`, `businessName`, `source`, `tags` | `eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists` |
| Identificadores e estados | `email`, `assignedTo`, `followers`, `country`, `timezone`, `type`, `dnd`, `validEmail`, `isValidWhatsapp`, `website` | `eq`, `not_eq`, `exists`, `not_exists` |
| Datas | `dateAdded`, `dateUpdated`, `dateOfBirth`, `lastActivity`, `lastEmailClickedDate`, `lastEmailOpenedDate`, `lastAppointment` | `range`, `exists`, `not_exists` |
| Workflow | `activeWorkflows`, `finishedWorkflows` | `eq`, `not_eq`, `exists`, `not_exists` |

\*O campo `contactName` aceita igualdade e verificação de existência; os operadores de conteúdo são aplicáveis aos campos de nomes em letras minúsculas. Cada campo aceita somente os operadores habilitados para ele.

Para `email` e `website`, os operadores `contains` e `not_contains` não estão disponíveis. Os filtros `email` e `phone` consideram o valor principal do contato; para procurar também os adicionais, utilize o campo textual `query` ou a [consulta de possível duplicado](https://docs.salez.com.br/contatos/pesquisa/consultar-duplicado.md).

### Campos personalizados

Utilize `customFields.{customFieldId}` no campo `field` do filtro. Os operadores aceitos dependem do tipo:

| Tipo do campo | Operadores |
| - | - |
| Texto, texto longo, seleção única, rádio e telefone | `eq`, `not_eq`, `contains`, `not_contains`, `exists`, `not_exists` |
| Caixa de seleção e múltipla escolha | `eq`, `not_eq`, `exists`, `not_exists` |
| Numérico e monetário | `eq`, `not_eq`, `range`, `exists`, `not_exists` |
| Data | `range`, `exists`, `not_exists` |

Para campos de lista de textos, utilize também `.{optionId}` ao final do caminho.

### Filtros de oportunidades

O filtro `opportunities` usa o operador `nested` e recebe uma lista de critérios sobre `pipelineId`, `pipelineStageId` ou `status`.

```json theme={"system"}
{
  "field": "opportunities",
  "operator": "nested",
  "value": [
    { "field": "pipelineStageId", "operator": "eq", "value": "<pipelineStageId>" },
    { "field": "status", "operator": "eq", "value": "open" }
  ]
}
```

### Paginação e ordenação

* `pageLimit` aceita até **500** registros por requisição. Se definido como `0`, retorna apenas a contagem.
* `page` começa em **1** e permite acessar até **10.000 resultados** na paginação convencional.
* Para ultrapassar esse limite, reutilize o `searchAfter` do último contato recebido na página anterior. Nesse modo, `page` é ignorado.
* `sort` permite até **dois critérios**, como `dateAdded` e `firstNameLowerCase`.
* Com `fastPagination: true`, a resposta informa `hasMore` em vez de `total`.

> [!NOTE]
>
> Consultas podem apresentar um pequeno atraso de indexação após alterações recentes. Para sincronizações incrementais, use `dateUpdated` com `range`, intervalos sobrepostos e deduplicação por `id`.


## OpenAPI

````yaml openapi.json POST /contacts/search
openapi: 3.0.0
info:
  title: Salez API
  version: v3
  description: >-
    Documentação da API da Salez para consultar, criar e atualizar contatos e
    consultar agendamentos. Para começar, veja a visão geral do módulo Contatos,
    com orientação sobre autenticação e permissões.
servers:
  - url: https://services.leadconnectorhq.com
    description: Servidor da API Salez.
security: []
tags:
  - name: Contatos
    description: Consulta e gerenciamento de contatos da Salez.
paths:
  /contacts/search:
    post:
      tags:
        - Contatos
      summary: Pesquisar contatos
      description: >-
        Pesquisa contatos com filtros avançados, paginação e ordenação. Para
        volumes superiores a 10 mil resultados, utilize `searchAfter`.
      operationId: salez-post-contacts-search
      parameters:
        - name: Version
          in: header
          description: 'Versão obrigatória da API: `v3`.'
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                locationId:
                  type: string
                  description: ID da subconta em que será feita a pesquisa.
                  example: ve9EPM428h8vShlRW1KT
                pageLimit:
                  type: integer
                  minimum: 0
                  maximum: 500
                  description: >-
                    Quantidade de contatos por página (máximo 500). Se zero,
                    retorna somente o total.
                  example: 20
                page:
                  type: integer
                  minimum: 1
                  description: >-
                    Página na paginação convencional. Ignorado quando
                    `searchAfter` é informado.
                  example: 1
                searchAfter:
                  type: array
                  description: >-
                    Cursor de paginação. Use o recebido no último resultado da
                    página anterior.
                  items:
                    oneOf:
                      - type: number
                      - type: string
                  example:
                    - 1700000000000
                    - seD4PfOuKoVMLkEZqohJ
                query:
                  type: string
                  maxLength: 75
                  description: Pesquisa textual em campos configurados como pesquisáveis.
                  example: Sara
                filters:
                  type: array
                  description: >-
                    Filtros de campo e grupos lógicos. Por padrão, os filtros de
                    nível superior são combinados com AND.
                  items:
                    $ref: '#/components/schemas/SalezSearchFilter'
                  example:
                    - field: city
                      operator: eq
                      value: São Paulo
                sort:
                  type: array
                  description: Critérios de ordenação, aplicados na sequência informada.
                  items:
                    $ref: '#/components/schemas/SalezSearchSort'
                  example:
                    - field: dateAdded
                      direction: desc
                assignedTo:
                  type: string
                  description: Filtra contatos atribuídos a um usuário.
                  example: hxHGVRb1YJUscrCB8eXK
                fastPagination:
                  type: boolean
                  description: >-
                    Quando true, retorna `hasMore` no lugar do total de
                    resultados.
                  example: false
              required:
                - locationId
                - pageLimit
      responses:
        '200':
          description: Resposta de sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalezSearchResults'
        '400':
          description: Requisição inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
        '401':
          description: Token inválido ou ausente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDTO'
        '422':
          description: Dados não processados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableDTO'
      security:
        - bearer: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request POST \
            --url 'https://services.leadconnectorhq.com/contacts/search' \
            --header 'Authorization: Bearer <token>' \
            --header 'Version: v3' \
            --header 'Content-Type: application/json' \
            --data '{
              "locationId": "ve9EPM428h8vShlRW1KT",
              "pageLimit": 20,
              "page": 1,
              "query": "Sara",
              "filters": [
                {
                  "field": "city",
                  "operator": "eq",
                  "value": "São Paulo"
                }
              ],
              "sort": [
                {
                  "field": "dateAdded",
                  "direction": "desc"
                }
              ],
              "fastPagination": false
            }'
components:
  schemas:
    SalezSearchFilter:
      type: object
      description: >-
        Filtro individual (field, operator e value) ou grupo lógico (group e
        filters).
      properties:
        field:
          type: string
          description: >-
            Campo pesquisável: por exemplo `city`, `email`, `tags`,
            `dateUpdated` ou `customFields.{customFieldId}`.
          example: city
        operator:
          type: string
          description: Operador de comparação suportado pelo campo.
          enum:
            - eq
            - not_eq
            - contains
            - not_contains
            - exists
            - not_exists
            - range
            - nested
          example: eq
        value:
          description: >-
            Valor a comparar. Não envie para `exists` ou `not_exists`. Para
            `range`, informe `gte`, `lte`, `gt` ou `lt`.
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
            - type: object
              additionalProperties: true
        group:
          type: string
          enum:
            - AND
            - OR
          description: Como combinar filtros internos.
          example: OR
        filters:
          type: array
          description: Filtros internos de um grupo lógico.
          items:
            type: object
            additionalProperties: true
    SalezSearchSort:
      type: object
      properties:
        field:
          type: string
          description: >-
            Campo de ordenação. Exemplos: `firstNameLowerCase`,
            `lastNameLowerCase`, `businessName`, `dateAdded`, `dateUpdated`,
            `email`, `dnd`, `source` ou `lastActivity`.
          example: dateAdded
        direction:
          type: string
          enum:
            - asc
            - desc
          description: Direção da ordenação.
          example: desc
    SalezSearchResults:
      type: object
      properties:
        contacts:
          type: array
          description: >-
            Contatos encontrados. O campo `searchAfter` permite buscar a página
            seguinte.
          items:
            allOf:
              - $ref: '#/components/schemas/GetContactByIdSchemaV3'
              - type: object
                properties:
                  searchAfter:
                    type: array
                    items:
                      oneOf:
                        - type: string
                        - type: number
                    example:
                      - 1700000000000
                      - seD4PfOuKoVMLkEZqohJ
                  followers:
                    type: array
                    description: IDs de usuários seguidores.
                    items:
                      type: string
                    example: []
        total:
          type: integer
          description: Total de contatos (omitido quando fastPagination=true).
          example: 120
        hasMore:
          type: boolean
          description: Há mais resultados quando fastPagination=true.
          example: true
    BadRequestDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        message:
          type: string
          example: Bad Request
    UnauthorizedDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          type: string
          example: 'Invalid token: access token is invalid'
        error:
          type: string
          example: Unauthorized
    UnprocessableDTO:
      type: object
      properties:
        statusCode:
          type: number
          example: 422
        message:
          example:
            - Unprocessable Entity
          type: array
          items:
            type: string
        error:
          type: string
          example: Unprocessable Entity
    GetContactByIdSchemaV3:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do contato.
          example: seD4PfOuKoVMLkEZqohJ
        name:
          type: string
          description: Nome completo do contato.
          example: Sara Muller
        locationId:
          type: string
          description: ID da subconta à qual o contato pertence.
          example: ve9EPM428h8vShlRW1KT
        firstName:
          type: string
          description: Primeiro nome do contato.
          example: Sara
        lastName:
          type: string
          description: Sobrenome do contato.
          example: Muller
        email:
          type: string
          description: Endereço de e-mail do contato.
          example: sara@salez.com.br
        emailLowerCase:
          type: string
          description: E-mail do contato em letras minúsculas.
          example: sara@salez.com.br
        timezone:
          type: string
          description: Fuso horário do contato.
          example: America/Sao_Paulo
        companyName:
          type: string
          description: Nome da empresa do contato.
          example: Salez
        phone:
          type: string
          description: Número de telefone do contato.
          example: '+5511934848735'
        dnd:
          type: boolean
          description: Indica se o modo não perturbe (DND) está habilitado para o contato.
          example: true
        type:
          type: string
          description: Classificação do tipo de contato.
          example: lead
        source:
          type: string
          description: Origem da criação do contato.
          example: Integração API
        assignedTo:
          type: string
          description: ID do usuário responsável pelo contato.
          example: ve9EPM428h8vShlRW1KT
        address1:
          type: string
          description: Endereço do contato.
          example: Av. Pres. Juscelino Kubitschek, 1327
        city:
          type: string
          description: Cidade do contato.
          example: São Paulo
        state:
          type: string
          description: Estado do contato.
          example: SP
        country:
          type: string
          description: País do contato.
          example: BR
        postalCode:
          type: string
          description: Código postal do contato.
          example: 04543-011
        website:
          type: string
          description: URL do site do contato.
          example: https://salez.com.br
        tags:
          description: Lista de etiquetas associadas ao contato.
          example:
            - cliente
            - atendimento
          type: array
          items:
            type: string
        dateOfBirth:
          type: string
          description: Data de nascimento do contato no formato YYYY-MM-DD.
          example: '1990-09-25'
        dateAdded:
          type: string
          description: Data e hora de criação do contato no padrão ISO 8601.
          example: '2021-07-02T05:18:26.704Z'
        dateUpdated:
          type: string
          description: Data e hora da última atualização do contato no padrão ISO 8601.
          example: '2021-07-02T05:18:26.704Z'
        ssn:
          type: string
          description: Número de seguridade social dos EUA (SSN), quando aplicável.
        keyword:
          type: string
          description: Palavra-chave de busca associada ao contato.
          example: test
        firstNameLowerCase:
          type: string
          description: Primeiro nome do contato em letras minúsculas.
          example: sara
        fullNameLowerCase:
          type: string
          description: Nome completo do contato em letras minúsculas.
          example: sara muller
        lastNameLowerCase:
          type: string
          description: Sobrenome do contato em letras minúsculas.
          example: muller
        lastActivity:
          type: string
          description: Data e hora da última atividade do contato no padrão ISO 8601.
          example: '2021-07-16T11:39:30.564Z'
        customFields:
          description: Lista de valores dos campos personalizados do contato.
          example:
            - id: 6dvNaf7VhkQ9snc5vnjJ
              key: contato.segmento
              fieldValue: Tecnologia
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldSchema'
        businessId:
          type: string
          description: ID da empresa associada ao contato.
          example: 641c094001436dbc2081e642
        attributionSource:
          description: Dados da origem de atribuição da primeira interação do contato.
          example:
            url: Trigger Link
            campaign: Summer Sale
          allOf:
            - $ref: '#/components/schemas/AttributionSource'
        lastAttributionSource:
          description: Dados da origem de atribuição da última interação do contato.
          example:
            url: Organic Search
            campaign: Brand Awareness
          allOf:
            - $ref: '#/components/schemas/AttributionSource'
        visitorId:
          type: string
          description: >-
            `visitorId` é o identificador único atribuído a cada visitante do
            chat ao vivo.
          example: ve9EPM428h8vShlRW1KT
        dndSettings:
          description: Configurações de não perturbe (DND) por canal do contato.
          example:
            call:
              status: inactive
            email:
              status: inactive
          allOf:
            - $ref: '#/components/schemas/DndSettingsSchemaV3'
    CustomFieldSchema:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do campo personalizado.
          example: MgobCB14YMVKuE4Ka8p1
        value:
          type: string
          description: Valor do campo personalizado.
          example: name
    AttributionSource:
      type: object
      properties:
        url:
          type: string
          description: Tipo de origem da atribuição.
          example: Trigger Link
        campaign:
          type: string
          description: Nome da campanha.
          example: Summer Sale 2024
          nullable: true
        utmSource:
          type: string
          description: Parâmetro UTM de origem.
          example: google
          nullable: true
        utmMedium:
          type: string
          description: Parâmetro UTM de meio.
          example: cpc
          nullable: true
        utmContent:
          type: string
          description: Parâmetro UTM de conteúdo.
          example: ad_variation_1
          nullable: true
        referrer:
          type: string
          description: URL de referência.
          example: https://www.google.com
          nullable: true
        campaignId:
          type: string
          description: ID da campanha.
          example: 641c094001436dbc2081e642
          nullable: true
        fbclid:
          type: string
          description: ID do clique no Facebook.
          example: fb.1.1674748390986.1171287961
          nullable: true
        gclid:
          type: string
          description: ID do clique no Google.
          example: >-
            CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB
          nullable: true
        msclikid:
          type: string
          description: ID do clique na Microsoft.
          example: MS!AzEREREDJKSJD
          nullable: true
        dclid:
          type: string
          description: ID do clique no DoubleClick.
          example: EAIaIQobChMIw
          nullable: true
        fbc:
          type: string
          description: ID do navegador no Facebook.
          example: fb.1.1674748390986.1171287961
          nullable: true
        fbp:
          type: string
          description: ID do pixel do Facebook.
          example: fb. 1.1674748390986.1171287961
          nullable: true
        fbEventId:
          type: string
          description: ID do evento no Facebook.
          example: Mozilla/5.0
          nullable: true
        userAgent:
          type: string
          description: Identificação do navegador no formato user agent.
          example: Mozilla/5.0
          nullable: true
        ip:
          type: string
          description: Endereço IP do visitante.
          example: 58.111.106.198
          nullable: true
        medium:
          type: string
          description: Meio de atribuição, como pesquisa ou funil.
          example: survey
          nullable: true
        mediumId:
          type: string
          description: ID do meio de atribuição.
          example: FglfHAn30PRwsZVyQlKp
          nullable: true
      required:
        - url
    DndSettingsSchemaV3:
      type: object
      properties:
        call:
          description: Configurações de não perturbe (DND) para chamadas telefônicas.
          example:
            status: active
            message: Do not call
            code: all
          allOf:
            - $ref: '#/components/schemas/DndSettingSchema'
        email:
          description: Configurações de não perturbe (DND) para e-mail.
          example:
            status: inactive
          allOf:
            - $ref: '#/components/schemas/DndSettingSchema'
        sms:
          description: Configurações de não perturbe (DND) para SMS.
          example:
            status: active
            message: Do not SMS
            code: all
          allOf:
            - $ref: '#/components/schemas/DndSettingSchema'
        whatsApp:
          description: Configurações de não perturbe (DND) para o WhatsApp.
          example:
            status: active
            message: Do not WhatsApp
            code: all
          allOf:
            - $ref: '#/components/schemas/DndSettingSchema'
        gmb:
          description: Configurações de não perturbe (DND) para o Google My Business.
          example:
            status: active
            message: Do not contact via GMB
            code: all
          allOf:
            - $ref: '#/components/schemas/DndSettingSchema'
        fb:
          description: Configurações de não perturbe (DND) para o Facebook.
          example:
            status: active
            message: Do not contact via FB
            code: all
          allOf:
            - $ref: '#/components/schemas/DndSettingSchema'
    DndSettingSchema:
      type: object
      properties:
        status:
          type: string
          description: Status de não perturbe (DND) para este canal.
          enum:
            - active
            - inactive
            - permanent
          example: active
        message:
          type: string
          description: >-
            Mensagem personalizada associada à configuração de não perturbe
            (DND).
          example: Do not contact via this channel
        code:
          type: string
          description: Código ou motivo de não perturbe (DND).
          example: OPTED_OUT
      required:
        - status
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use um token autorizado da subconta. Gere ou gerencie a integração em
        Configurações > Integrações Privadas na Salez, conforme as permissões do
        usuário. Informe o token no formato Bearer.
      type: http

````

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