Criar contato

POST/api/v1/contacts

Cria um contato. Email é único entre contatos ativos do workspace. Por padrão, email duplicado retorna 409 com o contato existente no body. Pra comportamento "find-or-create" (sem erro, retorna 200 com o existente), passe o header X-On-Conflict: return-existing · útil pra form do site que pode receber a mesma pessoa 2x.

Body (JSON)

`name`obrigatório string	Nome (1-120 caracteres).
`email` string \| null	Email válido · normalizado pra minúsculas.
`phone` string \| null	Telefone (max 30 caracteres).
`title` string \| null	Cargo (max 120 caracteres).
`accountId` string \| null	Empresa existente pra vincular (senão `404`).
`customFields` object	Objeto `{ chave: valor }` com as `key`s de custom fields de CONTACT (`GET /custom-fields?entity=CONTACT`).

Headers

`Idempotency-Key` string	Opcional, recomendado (8-200 caracteres, ex.: um UUID). A primeira request é processada normalmente; requests com a mesma key e mesmo body em até 24h retornam a resposta cacheada (header `Idempotency-Replay: true`), sem criar duplicata. Mesma key com body diferente retorna `422 IDEMPOTENCY_CONFLICT`. Só respostas 2xx são cacheadas.
`X-On-Conflict` enum	Comportamento em email duplicado: `error` (409 com o contato existente no body + header `X-Conflict-Behavior: existing-returned`) ou `return-existing` (200 com o existente + header `X-Found-Existing: true`). `errorreturn-existing` default: `error`

Resposta 201 Created (ou 200 no modo find-or-create, ou 409 no conflito default).

Suporta Idempotency-Key · replays com mesmo body em até 24h retornam a resposta cacheada sem duplicar (útil pra retries de n8n/Zapier).

Dispara webhook contact.created (só quando cria de fato).

Email de contato já soft-deletado é considerado vago e pode ser reusado.

Autenticação: header Authorization: Bearer rmk_... · veja Introdução e autenticação.

curl -X POST "https://crmdojordao.com.br/api/v1/contacts" \
  -H "Authorization: Bearer rmk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "João Silva", "email": "joao@empresaexemplo.com.br", "phone": "+5511999999999", "title": "Diretor Comercial", "accountId": "acc_empresa_exemplo", "customFields": { "fonte_lead": "Site" } }'

Request body

{
  "name": "João Silva",
  "email": "joao@empresaexemplo.com.br",
  "phone": "+5511999999999",
  "title": "Diretor Comercial",
  "accountId": "acc_empresa_exemplo",
  "customFields": {
    "fonte_lead": "Site"
  }
}

Resposta · POST /api/v1/contacts

{
  "id": "ct_joao",
  "name": "João Silva",
  "email": "joao@empresaexemplo.com.br",
  "phone": "+5511999999999",
  "title": "Diretor Comercial",
  "accountId": "acc_empresa_exemplo",
  "customFields": {
    "fonte_lead": "Site"
  },
  "createdAt": "2026-07-01T13:30:00.000Z",
  "updatedAt": "2026-07-01T13:30:00.000Z"
}