API — Contatos (/contacts)

CRUD completo de contatos via API: listar com filtros, criar, atualizar, excluir, buscar por telefone e listar negócios e conversas do contato. Inclui todos os parâmetros e o formato da resposta.

API — Contatos

Gerenciamento de contatos (leads, clientes, fornecedores). Base: /api/v1/contacts.

Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.
Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.

Endpoints

MétodoPathDescrição
GET/contactsListar contatos (paginado)
POST/contactsCriar contato
GET/contacts/by-phoneBuscar contato por telefone
GET/contacts/{id}Detalhes do contato
PUT/contacts/{id}Atualizar contato
DELETE/contacts/{id}Excluir (soft delete)
GET/contacts/{id}/dealsNegócios do contato
GET/contacts/{id}/conversationsConversas do contato

GET /contacts — filtros

ParâmetroTipoDescrição
searchstringBusca por nome, nome fantasia, e-mail, telefone, celular ou documento
typestringlead, customer, prospect, supplier
person_typestringindividual ou company
group_idintegerGrupo do contato
assigned_tointegerResponsável (user_id)
sourcestringOrigem
tagsarray|stringTags (array ou separadas por vírgula; combina com AND)
is_activebooleanAtivo/inativo
sort_bystringname, email, type, created_at, updated_at, last_contact_at
sort_dirstringasc ou desc (padrão desc)
per_pageintegerPadrão 50, máx 100
GET /api/v1/contacts?type=customer&search=joao&per_page=25

POST /contacts — campos

Obrigatório: name. Demais opcionais. Padrões: type=lead, person_type=individual.

CampoTipoRegras
namestringobrigatório, máx 255
trading_namestringnome fantasia
emailstringe-mail válido
phone / mobilestringtelefone / celular
website, company, positionstringdados profissionais
documentstringCPF ou CNPJ
state_registration / municipal_registrationstringIE / IM
person_typestringindividual | company
typestringlead | customer | prospect | supplier
sourcestringorigem
contact_group_idintegergrupo
assigned_tointegerresponsável
parent_idintegercontato pai (empresa do funcionário)
address, address_number, address_complement, neighborhood, city, state, zip_code, countrystringendereço
birth_datedatedata de nascimento
tagsarraylista de tags
notesstringmáx 5000
custom_fieldsobjectcampos personalizados (chave/valor)
notification_settingsobjectpreferências de notificação
POST /api/v1/contacts
{
  "name": "João Silva",
  "email": "joao@email.com",
  "phone": "11999887766",
  "type": "lead",
  "tags": ["vip", "indicação"]
}

Resposta 201 com o contato detalhado e "message": "Contact created successfully."

PUT /contacts/{id}

Aceita os mesmos campos do POST (todos opcionais), mais is_active e bot_protected (boolean). Tags enviadas substituem as anteriores.

GET /contacts/by-phone

Localiza um contato pelos dígitos do telefone/celular (ignora máscara). Útil para resolver o contato a partir do remote_jid recebido em webhooks. Mínimo 8 dígitos, senão 422.

GET /api/v1/contacts/by-phone?phone=558597096994

Retorna o mesmo objeto detalhado do GET /contacts/{id}. Não encontrado ⇒ 404.

Formato da resposta (resumido)

{
  "id": 42,
  "name": "João Silva",
  "trading_name": null,
  "display_name": "João Silva",
  "person_type": "individual",
  "type": "customer",
  "email": "joao@email.com",
  "phone": "1133334444",
  "mobile": "11999887766",
  "document": "000.000.000-00",
  "source": "whatsapp",
  "tags": ["vip"],
  "is_active": true,
  "group": { "id": 3, "name": "Clientes VIP" },
  "assigned_to": { "id": 5, "name": "Maria" },
  "deals_count": 2,
  "contracts_count": 1,
  "created_at": "2026-01-05T08:00:00-03:00",
  "updated_at": "2026-03-10T12:00:00-03:00"
}

O detalhe (show, store, update, by-phone) acrescenta: website, company, position, state_registration, municipal_registration, endereço completo, birth_date, notes, custom_fields, notification_settings, parent_id, bot_protected, last_contact_at e employees[] (funcionários vinculados).

GET /contacts/{id}/deals e /conversations

Listas paginadas (padrão 25, máx 100) com os negócios e as conversas do contato, respectivamente. Cada negócio traz id, title, value, currency, status, stage, responsável e datas. Cada conversa traz id, remote_jid, display_name, status, canal, responsável, unread_count e prévia da última mensagem.

api contatos contacts crm integração

Este artigo foi útil?

Artigos Relacionados