Tags

?name= casa por nome EXATO, ignorando acento e maiúscula/minúscula — ?name=vip encontra "VIP", "Vip" ou "vip", mas não "VIP Ouro". Útil pra checar se uma tag…

{ "id": "…", "name": "Lead quente", "color": "#EE710E", "applies_to": ["contact", "deal"], "created_at": "…" }
Campo Obrigatório Regras
name sim 1–40
color sim #rrggbb, ou #rrggbbaa com transparência
applies_to sim contact, company, deal — pelo menos um
Método Escopo Descrição
GET/api/tags tags:read Lista. Filtros: ?applies_to=, ?name=
POST/api/tags tags:write Cria (201). Nome repetido devolve a existente com created: false (200)
PATCH/api/tags/{id} tags:write Edita name, color, applies_to
DELETE/api/tags/{id} tags:write Exclui — veja a resposta especial abaixo

?name= casa por nome EXATO, ignorando acento e maiúscula/minúscula — ?name=vip encontra "VIP", "Vip" ou "vip", mas não "VIP Ouro". Útil pra checar se uma tag já existe antes de criar, sem paginar a lista inteira. Sem casamento, devolve lista vazia — nunca erro.

Aplicar e remover tag — uma rota por tipo de registro, todas com escopo tags:write:

Método Descrição
POST/api/contacts/{id}/tags Aplica no contato. Corpo: { "tag_id": "…" }
DELETE/api/contacts/{id}/tags/{tagId} Remove do contato (204)
POST/api/companies/{id}/tags Aplica na empresa. Corpo: { "tag_id": "…" }
DELETE/api/companies/{id}/tags/{tagId} Remove da empresa (204)
POST/api/deals/{id}/tags Aplica no negócio. Corpo: { "tag_id": "…" }
DELETE/api/deals/{id}/tags/{tagId} Remove do negócio (204)
  • Aplicar responde 200, não 201 (é um vínculo, não um registro novo), com o corpo { "data": { "entity": "contact", "entity_id": "…", "tag_id": "…", "applied": true } }.
  • Aplicar é idempotente: reaplicar a mesma tag responde sucesso, não erro.
  • applies_to é respeitado: aplicar tag de contato num negócio devolve 400.
  • Criar tag com nome existente não é erro — devolve a que existe. Seu fluxo pode chamar "cria a tag X" toda execução sem tratar conflito. Exceção: se a tag existente não servir para o applies_to que você pediu, a resposta é 409 — dizer "sucesso" ali seria mentira útil.
  • Renomear (PATCH) para um nome que já é de outra tag devolve 409.

O DELETE conta os vínculos antes de apagar e devolve 200 (não 204) com o tamanho do estrago:

{
  "data": {
    "id": "7c1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
    "removed_links": { "contacts": 12, "companies": 0, "deals": 3 }
  }
}

O campo tags some sem tags:read

Uma chave sem tags:read não recebe "tags": [] em contato, empresa ou negócio — o campo desaparece da resposta.

É proposital. Em JSON, campo ausente e lista vazia são afirmações diferentes: "tags": [] diz "consultei, e este registro não tem etiqueta nenhuma" — uma afirmação que a sua chave, sem o escopo, não tem como fazer honestamente. Se devolvêssemos [] mesmo assim, um fluxo do tipo "se o contato for VIP, mande para o vendedor sênior" trataria todo mundo como não-VIP, para sempre, sem nenhum sinal de que a informação nunca foi consultada.

Para detectar por programa, toda resposta com campo omitido traz:

x-salos-omitted-fields: tags

Com tags:read, um registro sem nenhuma etiqueta continua vindo com "tags": [] normalmente.