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) |
409de telefone repetido.POSTePATCHde contato devolvem409 conflict"Já existe um contato com esse telefone nesta organização." O telefone é único por conta. NoPOST, o erro traz oexisting_iddo contato que já tem esse telefone. Se o seu fluxo importa lista de terceiro, trate esse409como "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.