CRM do JordãoCRM do JordãoCentral de Ajuda

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)

nameobrigató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).
birthDate
string | null
Aniversário, "yyyy-mm-dd" (só a data, sem hora).
accountId
string | null
Empresa existente pra vincular (senão 404).
customFields
object
Objeto { chave: valor } com as keys 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 conflito de identidade. error (default) só checa email duplicado: 409 com o contato existente no body + header X-Conflict-Behavior: existing-returned. return-existing amplia a checagem pra email OU telefone (variantes com/sem 55 incluídas): acha o existente e devolve 200 + header X-Found-Existing: true. Se essa checagem ampliada achar mais de um contato, ou um telefone batendo com um contato de email diferente do enviado, a identidade é ambígua e a API responde 409 CONFLICT ("Identidade ambígua") sem criar nada — revise os contatos manualmente antes de tentar de novo.
errorreturn-existing
default: error
Resposta 201 Created (ou 200 no modo find-or-create, ou 409 no conflito default ou na identidade ambígua do modo return-existing).
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 ou telefone de contato já soft-deletado é considerado vago e pode ser reusado.
O contato criado é atribuído automaticamente a quem gerou a chave de API (se essa pessoa ainda for membro do workspace) · isso não aparece no corpo da resposta, mas define quem enxerga o contato em /clientes num workspace com carteira OWN ou TEAM.

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", "birthDate": "1985-03-15", "accountId": "acc_empresa_exemplo", "customFields": { "fonte_lead": "Site" } }'
Request body
{
  "name": "João Silva",
  "email": "joao@empresaexemplo.com.br",
  "phone": "+5511999999999",
  "title": "Diretor Comercial",
  "birthDate": "1985-03-15",
  "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",
  "birthDate": "1985-03-15",
  "accountId": "acc_empresa_exemplo",
  "customFields": {
    "fonte_lead": "Site"
  },
  "createdAt": "2026-07-01T13:30:00.000Z",
  "updatedAt": "2026-07-01T13:30:00.000Z"
}