Contatos

Base path: /api/v1/contacts Scopes: contacts:read | contacts:write

Contatos são pessoas físicas no seu CRM — leads, clientes, prospects. Cada contato pode estar associado a uma ou mais empresas e ter múltiplos negócios.

Lista contatos

GET /api/v1/contacts

Scope: contacts:read

Query params:

Param	Tipo	Default	Descrição
page	number	1	Página atual
pageSize	number	50	Itens por página (máx 100)
search	string	—	Busca em nome, email, telefone
ownerId	string	—	Filtra por owner
sortKey	string	createdAt	Campo de ordenação
sortOrder	asc | desc	desc	Direção

Exemplo:

cURL

curl "https://app.indutivacrm.com.br/api/v1/contacts?page=1&pageSize=20" \
  -H "X-API-Key: crm_live_..."

Resposta 200

{
  "data": [
    {
      "id": "ckl4z9w8v0001abcdef123456",
      "firstName": "Maria",
      "lastName": "Silva",
      "email": "maria@empresa.com.br",
      "phone": "+5511999999999",
      "ownerId": "ckl4z00...",
      "companyId": "ckl4z01...",
      "score": 87,
      "createdAt": "2026-05-22T14:30:00.000Z",
      "updatedAt": "2026-05-22T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 4823,
    "totalPages": 242,
    "hasNext": true,
    "hasPrev": false
  }
}

Busca avançada (com filtros)

POST /api/v1/contacts/search

Scope: contacts:read

Use quando precisar de filtros complexos que não cabem em query string (AND/OR, ranges, múltiplos valores).

Body:

{
  "filters": {
    "operator": "AND",
    "conditions": [
      { "field": "ownerId", "operator": "eq", "value": "ckl4z00..." },
      { "field": "score", "operator": "gte", "value": 80 },
      { "field": "createdAt", "operator": "after", "value": "2026-01-01T00:00:00Z" }
    ]
  },
  "page": 1,
  "pageSize": 50,
  "sortKey": "score",
  "sortOrder": "desc"
}

Busca um contato

GET /api/v1/contacts/:id

Scope: contacts:read

Retorna o contato com todos os campos padrão + valores das propriedades customizadas em customProperties.

curl https://app.indutivacrm.com.br/api/v1/contacts/ckl4z9w8v0001abcdef123456 \
  -H "X-API-Key: crm_live_..."

Resposta 404 se não existir ou foi soft-deletado.

Cria um contato

POST /api/v1/contacts

Scope: contacts:write

Body (campos):

Campo	Tipo	Obrigatório	Descrição
firstName	string	✅	Nome
lastName	string	—	Sobrenome
email	string	—	E-mail (validado, único por tenant)
phone	string	—	Telefone (E.164 recomendado, será normalizado)
companyId	string	—	ID da empresa associada
ownerId	string	—	ID do user dono
tags	string[]	—	Array de tag IDs
customProperties	object	—	{ propertyId: value } pra cada custom field

curl -X POST https://app.indutivacrm.com.br/api/v1/contacts \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999",
    "ownerId": "ckl4z00...",
    "customProperties": {
      "cargo": "Diretora Comercial",
      "industria": "Manufatura"
    }
  }'

Resposta 201 Created com o contato completo (incluindo id gerado).

Upsert por email/telefone

Pra “criar se não existe, atualizar se existe”, primeiro busque com GET /contacts?search=email@... ou trate o 409 duplicate_email na resposta do POST — ele retorna existingContactId que você usa pra fazer PATCH.

Atualiza um contato

PATCH /api/v1/contacts/:id

Scope: contacts:write

Atualização parcial — só envie os campos que mudaram. Campos omitidos ficam intactos.

curl -X PATCH https://app.indutivacrm.com.br/api/v1/contacts/ckl4z9w8v0001abcdef123456 \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone": "+5511988888888"}'

Deleta um contato

DELETE /api/v1/contacts/:id

Scope: contacts:write

Soft-delete — o registro fica no banco com deletedAt preenchido, sai das listagens normais. Pra recuperar, suporte interno.

Resposta 204 No Content.

Lista negócios de um contato

GET /api/v1/contacts/:id/deals

Scope: contacts:read

Retorna os deals associados, ordenados: abertos primeiro, depois updatedAt desc.

[
  {
    "id": "ckl4d01...",
    "title": "Proposta CRM Enterprise",
    "stageId": "ckl4s01...",
    "pipelineId": "ckl4p01...",
    "value": 12000,
    "currency": "BRL",
    "isWon": false,
    "isLost": false,
    "updatedAt": "2026-05-22T14:30:00.000Z"
  }
]

Erros específicos de contatos

Status	error	Cenário
409	duplicate_email	POST com email já existente. Inclui existingContactId na resposta
409	duplicate_phone	POST com telefone já existente (após normalização)
400	validation_failed	Campos obrigatórios faltando ou formato inválido
404	not_found	id não existe ou foi deletado

Veja Erros pra formato completo das respostas.