Contacts API

Endpoints para listar, criar e atualizar contatos (pessoas ou empresas). Contatos são a base para criação de leads.

GET{ENDPOINTS.contacts}contacts:read

Listar contatos com paginação e filtros

Query Parameters

Campo	Tipo	Descricao
`page`	number	Página atual (default: 1)
`limit`	number	Itens por página (default: 20, max: 100)
`search`	string	Busca por nome, email, telefone ou empresa
`email`	string	Filtrar por email exato
`phone`	string	Filtrar por telefone
`company`	string	Filtrar por empresa

Bash

curl "https://dev-api-tools.helbioads.com/api/v1/integration/contacts?search=silva&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta

JSON

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "clx123...",
        "externalId": "contact_001",
        "name": "João Silva",
        "email": "joao@email.com",
        "phone": "+5511999999999",
        "company": "Empresa ABC",
        "jobTitle": "Gerente",
        "city": "São Paulo",
        "state": "SP",
        "leadsCount": 3,
        "createdAt": "2024-01-10T08:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 85,
      "totalPages": 9
    }
  }
}

GET{ENDPOINTS.contacts}/:idcontacts:read

Buscar contato por ID ou externalId

Bash

curl "https://dev-api-tools.helbioads.com/api/v1/integration/contacts/clx123abc456" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST{ENDPOINTS.contacts}contacts:write

Criar novo contato

Body Parameters

Campo	Tipo	Descricao
`createContactIfNotFound`	boolean	Quando false, nao cria contato novo se nao encontrar referencia por protocol/externalId/email/phone. Retorna 404. Ex: `false`
`protocol`	string	Protocolo do Magic Link para vincular ao contato existente. Quando fornecido e encontrado, vincula os dados ao contato do Magic Link. Ex: `ML-20251030-143052-A8F3D-META`
`externalId`	string	Seu ID único para o contato. Obrigatório se protocol não for fornecido ou não encontrado.
`name`obrigatório	string	Nome completo
`email`	string	Email (usado para deduplicação)
`phone`	string	Telefone (formato internacional recomendado)
`mobilePhone`	string	Celular alternativo
`cpf`	string	CPF (usado para deduplicação)
`cnpj`	string	CNPJ da empresa
`company`	string	Nome da empresa
`jobTitle`	string	Cargo ou função
`website`	string	Website
`address`	string	Endereço
`city`	string	Cidade
`state`	string	Estado
`country`	string	País
`zipCode`	string	CEP
`customFields`	object	Campos customizados

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "contact-001",
    "name": "Maria Santos",
    "email": "maria@empresa.com",
    "phone": "+5511988888888",
    "company": "Empresa XYZ",
    "jobTitle": "Diretora de Marketing",
    "city": "São Paulo",
    "state": "SP",
    "customFields": {
      "segmento": "tecnologia",
      "tamanho_empresa": "100-500"
    }
  }'

Buscar sem criar contato

Use createContactIfNotFound: false quando quiser apenas vincular a um contato ja existente. Se nenhuma referencia for encontrada, a API retorna 404.

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "contact-001",
    "createContactIfNotFound": false,
    "email": "maria@empresa.com"
  }'

🔗 Vinculação por Protocolo (Magic Link)

Ao enviar o campo protocol, o sistema busca um contato existente criado via Magic Link. Se encontrado, os dados são vinculados a esse contato ao invés de criar um novo.

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "ML-20251030-143052-A8F3D-META",
    "name": "João Silva",
    "email": "joao@empresa.com",
    "phone": "+5511999999999"
  }'

💡 Dica: Envie protocol + externalIdjuntos para garantir fallback caso o protocolo não seja encontrado.

PATCH{ENDPOINTS.contacts}/:idcontacts:write

Atualizar contato existente

Bash

curl -X PATCH "https://dev-api-tools.helbioads.com/api/v1/integration/contacts/clx123abc456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobTitle": "CEO",
    "phone": "+5511977777777"
  }'

Deduplicação

O sistema detecta contatos duplicados automaticamente usando os seguintes campos (em ordem de prioridade):

externalId - Se já existe contato com mesmo externalId, atualiza
email - Se não tem externalId, busca por email
phone - Se não tem email, busca por telefone
cpf - Se não tem telefone, busca por CPF

Se nenhum campo corresponder, um novo contato é criado.

Próximos Passos

Leads API

Gerenciar leads

Tags API

Gerenciar tags