Tags

As tags ajudam a equipe de recrutamento a classificar e encontrar candidatos no pool de talentos da instância. Cada tag tem um nome único por instância e uma cor opcional, útil para destaque visual na interface.

As tags se vinculam aos candidatos em uma relação N:N. A sincronização dos vínculos não é feita aqui: ela acontece no update de candidatos, pelo atributo tagIds (veja a página Candidatos). Este recurso cuida apenas do catálogo de tags da instância.

Headers obrigatórios

Todas as requisições devem incluir o header X-Ats-Id (UUID) com o identificador da instância ATS, além de Authorization: Bearer {token} com o token do usuário do ATS (guard atsUser).

---

Estrutura de Dados Principal

Uma tag contém as seguintes informações principais:

Campo	Tipo	Descrição
id	Number	Identificador da tag.
name	String	Nome da tag (máx. 80 caracteres, único por instância).
color	String	Cor da tag em hexadecimal (máx. 9 caracteres, opcional).
createdAt	String	Data de criação (ISO 8601).
updatedAt	String	Data da última atualização (ISO 8601).

---

Endpoints de Consulta

Endpoints de leitura, disponíveis para qualquer usuário autenticado da instância.

Listar Tags

Lista as tags da instância, com paginação e busca por nome.

GET /v1/ats/user/tags

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
page	number	Não	O número da página (mínimo: 1).
perPage	number	Não	Itens por página (entre 1 e 100, padrão: 25).
search	string	Não	Busca por termo no nome (máx. 150 caracteres).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/tags?page=1&perPage=25" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de tags.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "name": "Prioridade Alta",
      "color": "#E63946",
      "createdAt": "2026-09-11T02:57:45.378+00:00"
    }
  ]
}

Listar Tags (Lista Simples)

Retorna as tags em formato simplificado (value/label), ordenadas por nome, ideal para selects e filtros no frontend.

GET /v1/ats/user/tags/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Filtra por prefixo do nome (máx. 150 caracteres).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/tags/list?search=Prio" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um array com as tags em formato value/label.

[
  {
    "value": 1,
    "label": "Prioridade Alta"
  }
]

Obter Tag por ID

Recupera os detalhes de uma tag da instância.

GET /v1/ats/user/tags/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da tag.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/tags/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna os dados da tag.

{
  "id": 1,
  "name": "Prioridade Alta",
  "color": "#E63946",
  "createdAt": "2026-09-11T02:57:45.378+00:00",
  "updatedAt": "2026-09-11T02:57:45.378+00:00"
}

404 Not Found

Ocorre quando a tag não existe na instância.

---

Endpoints de Gerenciamento

Endpoints de escrita do catálogo de tags. Exigem que o usuário autenticado seja owner/admin da instância ou tenha a role recruiter/hiring_manager em alguma empresa — demais roles recebem 403 Forbidden.

Criar Nova Tag

Cria uma nova tag na instância. O nome deve ser único entre as tags ativas da instância.

POST /v1/ats/user/tags

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da tag (máx. 80 caracteres, único por instância).
color	string	Não	Cor da tag em hexadecimal (máx. 9 caracteres).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/tags" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prioridade Alta",
    "color": "#E63946"
  }'

Respostas

201 Created

Retorna o ID da tag criada.

{
  "id": 1
}

403 Forbidden

O usuário autenticado não tem permissão para gerenciar tags.

{
  "message": "Você não tem permissão para gerenciar este recurso",
  "code": "FORBIDDEN"
}

422 Unprocessable Entity

Erro de validação nos campos enviados — por exemplo, nome ausente ou já utilizado por outra tag da instância.

{
  "errors": [
    {
      "message": "Nome é obrigatório",
      "rule": "required",
      "field": "name"
    }
  ]
}

Atualizar Tag

Atualiza o nome ou a cor de uma tag existente.

PUT /v1/ats/user/tags/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da tag.

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da tag (máx. 80 caracteres, único por instância).
color	string	Não	Cor da tag em hexadecimal (máx. 9 caracteres); envie null para remover.

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/tags/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prioridade Alta",
    "color": "#E63946"
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando a tag não existe na instância.

422 Unprocessable Entity

Erro de validação nos campos enviados — por exemplo, nome já utilizado por outra tag da instância.

Remover Tag

Remove uma tag da instância (exclusão lógica).

DELETE /v1/ats/user/tags/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID da tag.

Exemplo de Requisição

curl -X DELETE "https://api.us.basis.tavares.in/v1/ats/user/tags/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando a tag não existe na instância.