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

Escopos: contacts:read para os GET; contacts:write para POST e PATCH.

O recurso Contato

Campo	Tipo
`id`	uuid
`workspace_id`	uuid
`name`	string
`email`	string \| null
`phone`	string \| null
`phone2`	string \| null
`whatsapp`	string \| null
`job_title`	string \| null
`company_id`	uuid \| null
`owner_id`	uuid
`instagram`	string \| null
`linkedin`	string \| null
`notes`	string \| null
`custom_fields`	object \| null
`created_at`	datetime
`updated_at`	datetime

Listar contatos

GET {BASE_URL}/api-v1-contacts

Filtro (query)	Tipo	Notas
`email`	string	Igualdade exata (normalizado para minúsculas).
`company_id`	uuid
`since`	ISO 8601	`created_at >= since`.
`limit`	int	Padrão 50, máx 200.
`cursor`	uuid	Próxima página.

curl "{BASE_URL}/[email protected]" \
  -H "X-API-Key: vnd_sua_chave_aqui"

{
  "data": [ { "id": "1a2b...", "name": "Maria Silva", "email": "[email protected]", "...": "..." } ],
  "meta": { "next_cursor": null, "has_more": false }
}

Consultar um contato

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

Criar um contato

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

Campo	Tipo	Obrigatório
`name`	string	Sim (1–255).
`owner_id`	uuid	Não (resolução automática quando ausente).
`email`	string	Não (e-mail válido, minúsculas).
`phone`	string	Não
`phone2`	string	Não
`whatsapp`	string	Não
`job_title`	string	Não
`company_id`	uuid	Não (deve pertencer ao workspace).
`instagram`	string	Não
`linkedin`	string	Não
`notes`	string	Não (até 10.000).
`custom_fields`	object	Não (≤ 50 chaves, ≤ 10 KB).

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

Resposta 201 Created:

{ "id": "1a2b..." }

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.

Atualizar um contato

PATCH {BASE_URL}/api-v1-contacts/:id — escopo contacts:write. Mesmos campos do POST, todos opcionais. Retorna o contato completo atualizado (200 OK).

curl -X PATCH "{BASE_URL}/api-v1-contacts/1a2b..." \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "whatsapp": "+55 11 98888-0000" }'

Erros possíveis

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	Falta `contacts:read` ou `contacts:write`.
`404`	`not_found`	Contato não existe nesse workspace.
`400`	`bad_request`	Corpo ausente/JSON inválido.
`422`	`validation_error`	Campo inválido.
`422`	`invalid_reference`	`company_id`/`owner_id` fora do workspace.
`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).
`405`	`method_not_allowed`	Método não suportado.
`500`	`internal_error`	Falha interna.