API de Contatos: criar, listar, atualizar e buscar

Como gerenciar contatos do Omnifox pela API REST: criar, buscar, atualizar e mesclar duplicados.

Jul 11, 2026

A API de Contatos permite sincronizar sua base de clientes com sistemas externos (CRM, ERP, planilhas, automações) sem passar pela interface do Omnifox. Todos os endpoints ficam em /api/v1/contacts e exigem um token Bearer obtido em POST /api/v1/auth/login.

Requisitos

Token Bearer válido (Sanctum) para o workspace onde o contato existe.
Opcional: parâmetro ?workspace_id= se o seu token tiver acesso a mais de um workspace.

Endpoints principais

GET /api/v1/contacts — lista paginada, com filtros por tag, email, phone, country e campos personalizados via filter[cf.<chave>].
GET /api/v1/contacts/search — busca por texto livre.
POST /api/v1/contacts — cria um contato (first_name é o único campo obrigatório).
GET/PUT/DELETE /api/v1/contacts/{contact} — ver, atualizar ou excluir um contato específico.
POST /api/v1/contacts/upsert — cria ou atualiza com base em correspondência de e-mail/telefone/canal.
POST /api/v1/contacts/merge — mescla contatos duplicados.
POST /api/v1/contacts/{contact}/tags — adiciona etiquetas.

Campos ao criar um contato

{
  "first_name": "Maria",
  "last_name": "Garcia",
  "email": "[email protected]",
  "phone": "+593991234567",
  "country": "EC",
  "custom_fields": { "empresa": "Acme Corp" },
  "tags": ["VIP", "Prospecto"]
}

Exemplo: buscar contatos com a etiqueta VIP

curl -X GET "https://app.omnifox.io/api/v1/contacts?tag=VIP&per_page=50" \
  -H "Authorization: Bearer SEU_TOKEN"

A resposta traz a lista em data, além de meta (página atual, total) e links para navegação.

Dicas

Use upsert em integrações que recebem dados de formulários externos: evita duplicados por e-mail ou telefone.
O parâmetro include=custom_fields,channel_identities traz relacionamentos sem chamadas extras.
Antes de mesclar contatos com merge, confirme qual fica como "principal": a mesclagem não pode ser desfeita.

Solução de problemas

403 Forbidden: seu token não tem acesso a esse workspace; confira o workspace_id.
422 na criação: falta first_name, ou email/phone está em formato inválido.
Contato não aparece na busca: os filtros filter[cf.*] só valem para campos personalizados com entity_type=contact; verifique o nome interno (key) do campo em Configurações.

Isso foi útil?