Contatos

* editar external_id só funciona uma vez: pode DEFINIR num registro que ainda não tem, nunca TROCAR um que já tem — ver §27.

{
  "id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
  "name": "João Silva",
  "email": "joao.silva@exemplo.com.br",
  "phone": "+55 11 98888-0001",
  "title": "Comprador",
  "company_id": "4e8b2f6d-7a1c-4d5e-9f4b-8a2c6e1d3b84",
  "instagram": null,
  "messenger_id": null,
  "external_id": null,
  "custom_fields": {},
  "tags": [{ "id": "…", "name": "Lead quente", "color": "#EE710E" }],
  "created_at": "2026-05-02T12:00:00.000Z",
  "updated_at": "2026-05-02T12:00:00.000Z"
}
Campo Tipo Criar Editar Regras
name texto obrigatório opcional 1–120 caracteres
email texto | null opcional opcional e-mail válido, até 200
phone texto | null opcional opcional até 40
title texto | null opcional opcional cargo, até 120
company_id uuid | null opcional opcional precisa existir na conta
notes texto | null opcional opcional até 5000. Só escrita — vira uma anotação
instagram texto | null opcional opcional até 255. Usuário/id do Instagram — texto livre, sem validação de formato
messenger_id texto | null opcional opcional até 255. Id do Messenger — texto livre
tag_ids uuid[] opcional — (use §13) ≤ 50; precisam existir na conta e se aplicar a contato — um id inválido recusa a chamada INTEIRA (nada é gravado)
custom_fields objeto opcional opcional {"<key ou uuid>": valor} — ver §28
external_id texto | null opcional opcional* até 255. O id do registro na sua base de origem — ver "Importação: external_id" (§27)
tags lista — — só leitura, e só no GET

* editar external_id só funciona uma vez: pode DEFINIR num registro que ainda não tem, nunca TROCAR um que já tem — ver §27.

Método Escopo Descrição
GET/api/contacts contacts:read Lista. Filtros: ?search=, ?company_id=, ?external_id=, ?created_after=, ?created_before=, ?updated_after=, ?updated_before=, ?format=csv
GET/api/contacts/{id} contacts:read Um contato
POST/api/contacts contacts:write Cria (201)
PATCH/api/contacts/{id} contacts:write Edição parcial — só os campos enviados mudam
DELETE/api/contacts/{id} contacts:write Exclui (204)

409 de telefone repetido. POST e PATCH de contato devolvem 409 conflict "Já existe um contato com esse telefone nesta organização." O telefone é único por conta. No POST, o erro traz o existing_id do contato que já tem esse telefone. Se o seu fluxo importa lista de terceiro, trate esse 409 como "já tenho esse contato", não como falha.

?search= também acha por telefone. Num fluxo de WhatsApp, o que você tem em mãos é o número. Nome e e-mail buscam o texto cru; o telefone é normalizado antes da comparação, e só entra na busca quando o termo parece telefone (8 dígitos ou mais) — "Sala 12" nunca vira filtro de telefone.

Criar:

curl -X POST https://app.salos.com.br/api/contacts \
  -H "Authorization: Bearer $SALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "João Silva", "email": "joao@exemplo.com.br", "phone": "+55 11 98888-0001" }'

7.1 Anotações do contato

{
  "id": "…",
  "contact_id": "…",
  "title": "Ligou hoje",
  "content": "Ligou hoje, pediu proposta.",
  "author_name": null,
  "attachments": [],
  "created_at": "…",
  "updated_at": "…"
}
Método Escopo
GET/api/contacts/{id}/notes contacts:read
POST/api/contacts/{id}/notes contacts:write
PATCH/api/contacts/{id}/notes/{noteId} contacts:write
DELETE/api/contacts/{id}/notes/{noteId} contacts:write

Corpo: content (obrigatório na criação, até 5000) e title (opcional, até 120 — sem ele, o título é derivado do texto). Mandar title: "" é rejeitado com 400; omita o campo em vez de enviar texto vazio.

Uma anotação de outro contato responde 404 — o vínculo com o registro-pai é sempre conferido.

Autor e anexo (só com o escopo import:write)

Migrar uma base de outro CRM costuma trazer quem escreveu a anotação e arquivos anexados a ela — nenhum dos dois cabia no corpo content/title de sempre. Os três campos abaixo só existem numa chave com o escopo import:write; sem ele, mandá-los responde 400 forbidden_import_field nomeando o campo, e nada é gravado:

Campo Tipo O que faz
author_id uuid, opcional Precisa ser um usuário membro ATIVO desta conta. Vira created_by — a anotação passa a ter dono de verdade, igual a uma criada pela tela. Usuário que não pertence a esta conta (mesmo sendo um uuid válido) é recusado com 400, e nada é gravado — é o mesmo isolamento entre clientes que protege owner_id/assigned_to em outras rotas
author_name texto, opcional, até 120 Nome livre de quem escreveu, quando não existe de-para pra um usuário do Salos. created_by fica null e a tela mostra este nome no lugar
attachments lista, opcional, até 20 itens [{ "url": "https://…", "filename": "contrato.pdf", "mime_type": "application/pdf" }]. O Salos nunca baixa nem hospeda o arquivo — a tela só lista o link, aberto em nova aba. url tem que ser https://; http:// é recusado com 400

⛔ Data original da anotação (created_at/updated_at, também só com import:write) existe só na anotação de CONTATO. As anotações de empresa (§8.1) e de negócio (§9.1) não têm esses dois campos: mandá-los ali é 400 unknown_field, com ou sem o escopo, e a anotação nasce com a data de agora.

author_id e author_name são mutuamente exclusivos — mandando os dois, author_id prevalece (vira created_by, author_name não é gravado). O GET de uma anotação legada (gravada antes desses campos existirem) volta com "author_name": null, "attachments": [] — nunca null na lista de anexos.

⛔ Cada item de attachments tem os TRÊS campos obrigatórios — url (https://, nunca http://), filename (1–255) e mime_type (1–127). Faltando qualquer um, a chamada inteira é 400 e nada é gravado. CRM de origem que exporta só o endereço do arquivo precisa preencher os outros dois antes de enviar (o nome dá pra tirar do fim da URL; o tipo, da extensão).

⛔ A anotação NÃO devolve o id do registro-pai. Nada de contact_id, company_id ou deal_id no corpo da resposta de POST, PATCH e DELETE — você já tem esse id, é o {id} da própria URL que você chamou. ⚠️ A exceção é GET/POST/api/contacts/{id}/notes, que ainda devolvem contact_id: é assimetria conhecida do produto, não contrato. Não construa sincronização em cima desse campo — indexe pelo id que você usou na URL.