Saltar para o conteúdo principal
POST
cURL
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.

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.
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

*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.

Campos personalizados

Utilize customFields.{customFieldId} no campo field do filtro. Os operadores aceitos dependem do tipo: 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.

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.
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.

Autorizações

Authorization
string
header
obrigatório

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.

Cabeçalhos

Version
string
obrigatório

Versão obrigatória da API: v3.

Corpo

application/json
locationId
string
obrigatório

ID da subconta em que será feita a pesquisa.

Exemplo:

"ve9EPM428h8vShlRW1KT"

pageLimit
integer
obrigatório

Quantidade de contatos por página (máximo 500). Se zero, retorna somente o total.

Intervalo necessário: 0 <= x <= 500
Exemplo:

20

page
integer

Página na paginação convencional. Ignorado quando searchAfter é informado.

Intervalo necessário: x >= 1
Exemplo:

1

searchAfter
(number | string)[]

Cursor de paginação. Use o recebido no último resultado da página anterior.

Exemplo:
query
string

Pesquisa textual em campos configurados como pesquisáveis.

Maximum string length: 75
Exemplo:

"Sara"

filters
object[]

Filtros de campo e grupos lógicos. Por padrão, os filtros de nível superior são combinados com AND.

Exemplo:
sort
object[]

Critérios de ordenação, aplicados na sequência informada.

Exemplo:
assignedTo
string

Filtra contatos atribuídos a um usuário.

Exemplo:

"hxHGVRb1YJUscrCB8eXK"

fastPagination
boolean

Quando true, retorna hasMore no lugar do total de resultados.

Exemplo:

false

Resposta

Resposta de sucesso.

contacts
object[]

Contatos encontrados. O campo searchAfter permite buscar a página seguinte.

total
integer

Total de contatos (omitido quando fastPagination=true).

Exemplo:

120

hasMore
boolean

Há mais resultados quando fastPagination=true.

Exemplo:

true

Última modificação em 20 de novembro de 2026