Candidatos

Os candidatos formam o pool de talentos da sua instância ATS: cada pessoa é registrada uma única vez, independentemente de quantas vagas ela se candidate. A mesma pessoa pode ter candidaturas em vagas de empresas diferentes, e todo o histórico fica centralizado em um único perfil.

O cadastro é feito pelo próprio candidato no portal público (endpoints /v1/ats/candidate/candidates/register e /login). Por isso, na visão do staff não existem endpoints de criação nem de exclusão — o time de recrutamento consulta, enriquece o perfil com skills e tags, e pode bloquear um candidato quando necessário.

Headers obrigatórios

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

Estrutura de Dados Principal

Um candidato contém as seguintes informações principais:

Campo	Tipo	Descrição
`firstName`	`String`	Nome do candidato.
`lastName`	`String`	Sobrenome do candidato.
`email`	`String`	E-mail de acesso ao portal.
`phone`	`String`	Telefone de contato.
`headline`	`String`	Título profissional (ex.: "Desenvolvedora Full Stack Plena").
`summary`	`String`	Resumo profissional.
`city` / `country`	`String`	Localização do candidato.
`skills`	`Array`	Lista de habilidades do candidato.
`experiences`	`Array`	Experiências profissionais (`title`, `company`, `startDate`, `endDate`, `current`, `description`).
`educations`	`Array`	Formação acadêmica (`degree`, `institution`, `startDate`, `endDate`).
`links`	`Object`	Links externos (ex.: `github`, `linkedin`).
`isBlocked`	`Boolean`	Indica se o candidato está bloqueado.
`atsTags`	`Array`	Tags vinculadas pelo time (`id`, `name`, `color`).
`atsFiles`	`Array`	Arquivos enviados pelo candidato (ex.: currículo).
`atsApplications`	`Array`	Candidaturas do candidato, com a vaga (`atsJob`) e a etapa atual (`atsStage`).

Endpoints do Staff

Endpoints protegidos para consulta e gerenciamento do pool de talentos. Requerem autenticação de usuário do ATS (atsUser).

Listar Candidatos

Lista os candidatos da instância com paginação e filtros. A busca por search é full-text sobre o perfil do candidato.

http

GET /v1/ats/user/candidates

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 full-text no perfil do candidato (máx. 150 caracteres).
`skills`	`array`	Não	Filtra candidatos que possuem todas as skills informadas (ex.: `skills[]=Node.js`).
`city`	`string`	Não	Filtra por cidade (busca parcial, máx. 100 caracteres).
`country`	`string`	Não	Filtra por país (busca parcial, máx. 100 caracteres).
`isBlocked`	`boolean`	Não	Filtra por candidatos bloqueados (`true`) ou não bloqueados (`false`).
`orderBy`	`enum`	Não	Ordena por `id`, `firstName`, `email` ou `createdAt` (padrão: `id`).
`orderDirection`	`enum`	Não	Direção da ordenação: `asc` ou `desc` (padrão: `desc`).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/candidates?skills[]=Node.js&city=São Paulo&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 candidatos com suas tags.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "firstName": "Maria",
      "lastName": "Silva",
      "email": "maria.silva@email.com",
      "phone": "+55 11 98765-4321",
      "headline": "Desenvolvedora Full Stack Plena",
      "city": "São Paulo",
      "country": "Brasil",
      "skills": [
        "Node.js",
        "TypeScript",
        "React",
        "PostgreSQL",
        "Redis"
      ],
      "isBlocked": false,
      "createdAt": "2026-09-11T01:19:59.812+00:00",
      "atsTags": []
    }
  ]
}

422 Unprocessable Entity

Ocorre quando os parâmetros de paginação ou ordenação são inválidos.

Listar Candidatos (Lista Simples)

Retorna os candidatos em formato simplificado (value/label), ideal para selects no frontend. Limitado a 500 itens, ordenado por nome.

http

GET /v1/ats/user/candidates/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Busca por termo no nome, sobrenome ou e-mail (máx. 150 caracteres).

Exemplo de Requisição

bash

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

Respostas

200 OK

Retorna um array com os candidatos em formato value/label.

json

[
  {
    "value": 1,
    "label": "Maria Silva"
  }
]

Obter Candidato por ID

Recupera o perfil completo de um candidato, incluindo experiências, formação, links, tags, arquivos enviados e todas as suas candidaturas (com a vaga e a etapa atual de cada uma).

http

GET /v1/ats/user/candidates/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do candidato.

Exemplo de Requisição

bash

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

Respostas

200 OK

Retorna o perfil completo do candidato com atsTags, atsFiles e atsApplications.

json

{
  "id": 1,
  "atsId": 1,
  "firstName": "Maria",
  "lastName": "Silva",
  "email": "maria.silva@email.com",
  "phone": "+55 11 98765-4321",
  "lastIp": null,
  "lastLoginAt": null,
  "headline": "Desenvolvedora Full Stack Plena",
  "summary": "Desenvolvedora full stack com 5 anos de experiência em Node.js, TypeScript e React.",
  "city": "São Paulo",
  "country": "Brasil",
  "timezone": "America/Sao_Paulo",
  "skills": [
    "Node.js",
    "TypeScript",
    "React",
    "PostgreSQL",
    "Redis"
  ],
  "experiences": [
    {
      "title": "Desenvolvedora Full Stack Plena",
      "company": "Tech Corp",
      "current": true,
      "endDate": null,
      "startDate": "2022-03",
      "description": "Desenvolvimento de APIs REST e interfaces web para o produto principal da empresa."
    }
  ],
  "educations": [
    {
      "degree": "Bacharelado em Ciência da Computação",
      "endDate": "2019-12",
      "startDate": "2016-02",
      "institution": "Universidade de São Paulo"
    }
  ],
  "links": {
    "github": "https://github.com/mariasilva",
    "linkedin": "https://www.linkedin.com/in/maria-silva"
  },
  "resumeText": null,
  "isBlocked": false,
  "consentAt": "2026-09-11T02:34:31.598+00:00",
  "consentSource": "job_board",
  "purgeAfterAt": null,
  "createdAt": "2026-09-11T01:19:59.812+00:00",
  "updatedAt": "2026-09-11T02:34:31.603+00:00",
  "atsFiles": [
    {
      "id": 1,
      "name": "curriculo.pdf",
      "extension": "pdf",
      "size": 115579,
      "mime": "application/pdf",
      "url": "https://s3.sa-east-1.amazonaws.com/tavares-dev/files/7af7ff84-4b0e-4ee8-becb-308d88dc7997.pdf",
      "createdAt": "2026-09-11T01:28:40.053+00:00",
      "atsCandidateId": 1
    }
  ],
  "atsTags": [],
  "atsApplications": [
    {
      "id": 1,
      "atsJobId": 1,
      "atsStageId": 1,
      "atsCandidateId": 1,
      "status": "withdrawn",
      "appliedAt": "2026-09-11T02:34:31.641+00:00",
      "createdAt": "2026-09-11T02:34:31.648+00:00",
      "atsStage": {
        "id": 1,
        "name": "New"
      },
      "atsJob": {
        "id": 1,
        "title": "Desenvolvedor Full Stack Pleno"
      }
    }
  ]
}

404 Not Found

Ocorre quando o candidato não existe na instância.

Atualizar Candidato

Atualiza o perfil de um candidato. Use tagIds para sincronizar as tags vinculadas (a lista enviada substitui completamente a anterior) e isBlocked para bloquear ou desbloquear o candidato.

Todos os campos são opcionais; envie apenas o que deseja alterar. Usuários com papel viewer em todas as empresas não podem executar esta ação.

http

PUT /v1/ats/user/candidates/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do candidato.

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`skills`	`array`	Não	Lista de habilidades do candidato (array de strings).
`headline`	`string`	Não	Título profissional (máx. 200 caracteres).
`summary`	`string`	Não	Resumo profissional (máx. 5000 caracteres).
`city`	`string`	Não	Cidade (máx. 100 caracteres).
`country`	`string`	Não	País (máx. 100 caracteres).
`isBlocked`	`boolean`	Não	Bloqueia (`true`) ou desbloqueia (`false`) o candidato.
`tagIds`	`array`	Não	IDs das tags a vincular (devem existir na instância). Substitui as tags atuais.

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/candidates/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": "Desenvolvedora Full Stack Plena",
    "summary": "Profissional com 5 anos de experiência em desenvolvimento web, atuando com Node.js, TypeScript e React.",
    "city": "São Paulo",
    "country": "Brasil",
    "skills": ["Node.js", "TypeScript", "React", "PostgreSQL"],
    "isBlocked": false,
    "tagIds": [1]
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não tem permissão para gerenciar candidatos (papel viewer em todas as empresas).

json

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

404 Not Found

Ocorre quando o candidato não existe na instância.

422 Unprocessable Entity

Erro de validação nos campos enviados — por exemplo, um tagIds com tag inexistente ou de outra instância.

json

{
  "errors": [
    {
      "message": "The tagIds.0 field must exist",
      "rule": "database.exists",
      "field": "tagIds.0"
    }
  ]
}

Candidatos ​

Estrutura de Dados Principal ​

Endpoints do Staff ​

Listar Candidatos ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Listar Candidatos (Lista Simples) ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Obter Candidato por ID ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Atualizar Candidato ​

Parâmetros de Rota ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Candidatos

Estrutura de Dados Principal

Endpoints do Staff

Listar Candidatos

Parâmetros de Query

Exemplo de Requisição

Respostas

Listar Candidatos (Lista Simples)

Parâmetros de Query

Exemplo de Requisição

Respostas

Obter Candidato por ID

Parâmetros de Rota

Exemplo de Requisição

Respostas

Atualizar Candidato

Parâmetros de Rota

Payload (Body)

Exemplo de Requisição

Respostas