Contatos

GET    {BASE_URL}/api-v1-contacts      # lista
GET    {BASE_URL}/api-v1-contacts/:id  # detalhe
POST   {BASE_URL}/api-v1-contacts      # cria
PATCH  {BASE_URL}/api-v1-contacts/:id  # atualiza

Use os endereços acima — são os que respondem hoje. A API está migrando para um endereço único ({BASE_URL}/api-v1/contacts), que ainda não foi publicado: enquanto isso, qualquer chamada para ele devolve 404 not_found. Quando entrar no ar, esta página muda junto, e os endereços acima continuam valendo.

Escopos: contacts:read para os GET; contacts:write para a escrita.

Campos

Campo	Tipo	Escrita	Notas
`id`	uuid	somente leitura
`workspace_id`	uuid	somente leitura	Sempre o workspace da chave de API usada na chamada.
`name`	string	criar: obrigatório, editar: sim	De 1 a 255 caracteres.
`email`	string	criar: opcional, editar: sim	Formato email; máximo 255 caracteres; normalizado para minúsculas.
`phone`	string	criar: opcional, editar: sim	Máximo 40 caracteres.
`phone2`	string	criar: opcional, editar: sim	Máximo 40 caracteres.
`whatsapp`	string	criar: opcional, editar: sim	Máximo 40 caracteres.
`job_title`	string	criar: opcional, editar: sim	Máximo 255 caracteres.
`company_id`	uuid	criar: opcional, editar: sim	Formato uuid; deve existir na ficha `companies`.
`owner_id`	uuid	criar: opcional, editar: sim	Formato uuid; deve existir na ficha `owners`.
`instagram`	string	criar: opcional, editar: sim	Máximo 255 caracteres.
`linkedin`	string	criar: opcional, editar: sim	Máximo 255 caracteres.
`notes`	string	criar: opcional, editar: sim	Máximo 10000 caracteres.
`custom_fields`	objeto	criar: opcional, editar: sim	Objeto chave→valor. As chaves são as definidas na ficha `custom-fields`. até 50 chaves; até 10 KB; omitido → `{}`.
`created_at`	datetime	somente leitura
`updated_at`	datetime	somente leitura

Listar contatos

GET {BASE_URL}/api-v1-contacts

Parâmetro (query)	Tipo	Notas
`email`	string	Igualdade exata, sempre em minúsculas.
`company_id`	uuid
`since`	datetime	Só registros criados a partir desta data (ISO 8601). Compara: maior ou igual a.
`limit`	number	Tamanho da página. Padrão 50, máximo 200.
`cursor`	uuid	Próxima página — use o `meta.next_cursor` da resposta anterior.

Ordenação: id crescente. Paginação por cursor.

curl "{BASE_URL}/api-v1-contacts?email=..." \
  -H "X-API-Key: vnd_sua_chave_aqui"

{
  "data": [ /* registros */ ],
  "meta": { "next_cursor": "8f3c...", "has_more": true }
}

Consultar um registro

GET {BASE_URL}/api-v1-contacts/:id → o recurso completo, ou 404 not_found.

curl "{BASE_URL}/api-v1-contacts/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui"

Criar

POST {BASE_URL}/api-v1-contacts — escopo contacts:write.

Campo	Tipo	Obrigatório	Notas
`name`	string	Sim	De 1 a 255 caracteres.
`email`	string	Não	Formato email; máximo 255 caracteres; normalizado para minúsculas.
`phone`	string	Não	Máximo 40 caracteres.
`phone2`	string	Não	Máximo 40 caracteres.
`whatsapp`	string	Não	Máximo 40 caracteres.
`job_title`	string	Não	Máximo 255 caracteres.
`company_id`	uuid	Não	Formato uuid; deve existir na ficha `companies`.
`owner_id`	uuid	Não	Formato uuid; deve existir na ficha `owners`.
`instagram`	string	Não	Máximo 255 caracteres.
`linkedin`	string	Não	Máximo 255 caracteres.
`notes`	string	Não	Máximo 10000 caracteres.
`custom_fields`	objeto	Não	Objeto chave→valor. As chaves são as definidas na ficha `custom-fields`. até 50 chaves; até 10 KB; omitido → `{}`.

curl -X POST "{BASE_URL}/api-v1-contacts" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "..." }'

Atualizar

PATCH {BASE_URL}/api-v1-contacts/:id — escopo contacts:write. Todos os campos são opcionais; só o que vier no corpo muda.

Campo	Tipo	Obrigatório	Notas
`name`	string	Não	De 1 a 255 caracteres.
`email`	string	Não	Formato email; máximo 255 caracteres; normalizado para minúsculas.
`phone`	string	Não	Máximo 40 caracteres.
`phone2`	string	Não	Máximo 40 caracteres.
`whatsapp`	string	Não	Máximo 40 caracteres.
`job_title`	string	Não	Máximo 255 caracteres.
`company_id`	uuid	Não	Formato uuid; deve existir na ficha `companies`.
`owner_id`	uuid	Não	Formato uuid; deve existir na ficha `owners`.
`instagram`	string	Não	Máximo 255 caracteres.
`linkedin`	string	Não	Máximo 255 caracteres.
`notes`	string	Não	Máximo 10000 caracteres.
`custom_fields`	objeto	Não	Objeto chave→valor. As chaves são as definidas na ficha `custom-fields`. até 50 chaves; até 10 KB; omitido → `{}`.

curl -X PATCH "{BASE_URL}/api-v1-contacts/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "email": "...", "phone": "..." }'

Webhooks desta ficha

contact.created

Formato do envio, cabeçalhos e verificação da assinatura em Webhooks.

Erros

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	A chave não tem `contacts:read` / `contacts:write`.
`404`	`not_found`	O registro não existe neste cliente.
`422`	`validation_error`	Campo fora das regras da tabela acima.
`422`	`invalid_reference`	`company_id`, `owner_id` aponta para fora deste cliente.
`422`	`invalid_cursor`	O `cursor` enviado não é válido.
`405`	`method_not_allowed`	Método não suportado neste endereço.
`500`	`internal_error`	Falha interna.

Catálogo completo em Erros.

Idempotência

Envie um header Idempotency-Key (1–255 caracteres, qualquer string única sua) para tornar o POST acima seguro de reenviar em caso de timeout de rede ou retry automático:

curl -X POST "{BASE_URL}/api-v1-contacts" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-9f21" \
  -d '{ "name": "João Souza", "email": "[email protected]" }'

Mesma chave, mesmo corpo: a segunda chamada não cria outro contato — responde 200 OK com o corpo da resposta original (não 201), e o webhook contact.created não é reemitido.
Mesma chave, corpo diferente (ou reusada em outro recurso): 422 idempotency_conflict.
Mesma chave, requisição original ainda processando: 409 idempotency_in_progress — duas chamadas concorrentes com a mesma chave; espere e tente de novo.
Janela: a chave fica registrada por 24 horas; depois disso pode ser reusada como se fosse nova.
Sem o header: comportamento idêntico ao de hoje — cada POST cria um contato novo.

Erros específicos desta ficha

HTTP	`code`	Quando
`400`	`bad_request`	Corpo ausente/JSON inválido.
`422`	`no_owner_available`	Sem responsável ativo possível.
`400`	`invalid_idempotency_key`	`Idempotency-Key` fora de 1–255 caracteres.
`422`	`idempotency_conflict`	Mesma `Idempotency-Key` com corpo ou recurso diferente.
`409`	`idempotency_in_progress`	Mesma `Idempotency-Key` já em processamento (corrida).

Contatos

Nesta página