Basis

Appearance

Vagas ​

As vagas são o coração do ATS: cada vaga representa uma posição aberta na empresa e concentra a descrição do cargo, requisitos, benefícios, faixa salarial e o pipeline por onde os candidatos vão fluir. Toda vaga nasce como rascunho (draft) e só aparece no job board público quando é publicada.

Além dos dados da vaga em si, é possível configurar perguntas personalizadas que o candidato responde no momento da candidatura — incluindo perguntas eliminatórias (knockout), que filtram automaticamente quem não atende aos requisitos mínimos.

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 de um usuário staff (guard atsUser).

Estrutura de Dados Principal ​

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

CampoTipoDescrição
codeStringCódigo interno da vaga (ex.: REQ-2026-001).
titleStringTítulo da vaga (máx. 200 caracteres). O slug é gerado automaticamente a partir dele.
descriptionStringDescrição completa da vaga (suporta Markdown).
requirementsStringRequisitos do cargo.
benefitsStringBenefícios oferecidos.
statusEnumdraft, open, paused, closed ou archived.
employmentTypeEnumfull_time, part_time, contract, temporary, internship, freelance ou apprenticeship.
workplaceTypeEnumonsite, hybrid ou remote.
seniorityEnumintern, junior, mid, senior, lead, manager, director ou executive.
openingsNumberQuantidade de posições abertas (padrão: 1).
salaryMin / salaryMaxStringFaixa salarial (valores decimais retornados como string, ex.: "8000.00").
salaryCurrencyStringMoeda do salário (código ISO de 3 letras, ex.: BRL).
salaryPeriodEnumPeriodicidade do salário: hour, day, week, month ou year.
salaryIsPublicBooleanQuando false (padrão), o salário não é exibido no job board público.
publishedAtDateTimePreenchido automaticamente na primeira publicação.
closesAtDateTimeData limite para candidaturas.
closedAtDateTimePreenchido automaticamente ao fechar a vaga; limpo ao reabrir.
metadataObjectDados livres em formato JSON.

Gerenciamento de Vagas ​

Listar Vagas ​

Lista as vagas da instância com paginação, busca full-text e filtros. A busca por search percorre título, requisitos e descrição e não diferencia acentos — buscar por Engenheiro também encontra "Engenhéiro".

http
GET /v1/ats/user/jobs

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
pagenumberNãoO número da página (mínimo: 1).
perPagenumberNãoItens por página (entre 1 e 100, padrão: 25).
searchstringNãoBusca full-text em título, requisitos e descrição (máx. 150 caracteres).
orderByenumNãoOrdena por id, title, createdAt ou publishedAt.
orderDirectionenumNãoDireção da ordenação: asc ou desc.
statusenumNãoFiltra por draft, open, paused, closed ou archived.
atsCompanyIdnumberNãoFiltra por empresa.
atsDepartmentIdnumberNãoFiltra por departamento.
atsLocationIdnumberNãoFiltra por localidade.
workplaceTypeenumNãoFiltra por onsite, hybrid ou remote.
employmentTypeenumNãoFiltra pelo tipo de contratação.
seniorityenumNãoFiltra pelo nível de senioridade.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/jobs?status=open&workplaceType=remote" \
  -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 vagas.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "atsId": 1,
      "atsCompanyId": 1,
      "atsPipelineId": 1,
      "atsDepartmentId": 1,
      "atsLocationId": 1,
      "atsUserId": 1,
      "atsHiringUserId": 1,
      "code": "REQ-2026-001",
      "title": "Desenvolvedor Full Stack Pleno",
      "slug": "desenvolvedor-full-stack-pleno",
      "status": "draft",
      "employmentType": "full_time",
      "workplaceType": "hybrid",
      "seniority": "mid",
      "openings": 2,
      "salaryMin": "8000.00",
      "salaryMax": "12000.00",
      "salaryCurrency": "BRL",
      "salaryPeriod": "month",
      "salaryIsPublic": true,
      "publishedAt": null,
      "closesAt": "2026-10-15T00:00:00.000Z",
      "closedAt": null,
      "createdAt": "2026-09-10T16:08:24.207+00:00",
      "updatedAt": "2026-09-10T16:08:24.207+00:00",
      "atsDepartment": {
        "id": 1,
        "name": "I.T"
      },
      "atsCompany": {
        "id": 1,
        "name": "Catho"
      },
      "atsPipeline": {
        "id": 1,
        "name": "Default"
      },
      "atsLocation": {
        "id": 1,
        "name": "Av. Dr. Luís Rocha Miranda"
      }
    }
  ]
}

Listar Vagas (Lista Simples) ​

Retorna as vagas em formato simplificado (label/value), ideal para selects e filtros no frontend.

http
GET /v1/ats/user/jobs/list

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
searchstringNãoBusca por termo no título (máx. 150 caracteres).
statusenumNãoFiltra por draft, open, paused, closed ou archived.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/jobs/list?status=open" \
  -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 vagas em formato label/value.

json
[
  {
    "value": 1,
    "label": "Desenvolvedor Full Stack Pleno"
  }
]

Criar Vaga ​

Cria uma nova vaga. Toda vaga é criada com status draft e o slug é gerado automaticamente a partir do título.

http
POST /v1/ats/user/jobs

Payload (Body) ​

AtributoTipoObrigatórioDescrição
codestringNãoCódigo interno da vaga (máx. 40 caracteres).
titlestringSimTítulo da vaga (máx. 200 caracteres).
descriptionstringSimDescrição completa da vaga.
requirementsstringNãoRequisitos do cargo.
benefitsstringNãoBenefícios oferecidos.
employmentTypeenumNãoTipo de contratação (ver enums acima).
workplaceTypeenumNãoModelo de trabalho: onsite, hybrid ou remote.
seniorityenumNãoNível de senioridade.
openingsnumberNãoQuantidade de posições (mínimo: 1).
salaryMinnumberNãoSalário mínimo.
salaryMaxnumberNãoSalário máximo.
salaryCurrencystringNãoMoeda (3 letras, ex.: BRL).
salaryPeriodenumNãohour, day, week, month ou year.
salaryIsPublicbooleanNãoExibe o salário no job board público (padrão: false).
closesAtdateNãoData limite para candidaturas.
atsCompanyIdnumberSimID da empresa (deve existir na instância).
atsPipelineIdnumberSimID do pipeline (deve existir na instância).
atsDepartmentIdnumberNãoID do departamento (deve existir na instância).
atsLocationIdnumberNãoID da localidade (deve existir na instância).
atsUserIdnumberNãoID do usuário responsável pela vaga.
atsHiringUserIdnumberNãoID do hiring manager.
metadataobjectNãoDados livres em formato JSON.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/jobs" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "REQ-2026-001",
    "title": "Desenvolvedor Full Stack Pleno",
    "description": "## Sobre a vaga\n\nBuscamos um desenvolvedor full stack para atuar no produto principal da empresa.",
    "requirements": "- Experiência sólida com Node.js e TypeScript\n- Vivência com PostgreSQL e Redis",
    "benefits": "- Vale-refeição de R$ 880\n- Plano de saúde e odontológico",
    "employmentType": "full_time",
    "workplaceType": "hybrid",
    "seniority": "mid",
    "openings": 2,
    "salaryMin": 8000,
    "salaryMax": 12000,
    "salaryCurrency": "BRL",
    "salaryPeriod": "month",
    "salaryIsPublic": true,
    "closesAt": "2026-10-15",
    "atsCompanyId": 1,
    "atsPipelineId": 1,
    "atsDepartmentId": 1,
    "atsLocationId": 1
  }'

Respostas ​

201 Created

Retorna o ID da vaga criada.

json
{
  "id": 1
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json
{
  "errors": [
    {
      "message": "Título é obrigatório",
      "rule": "required",
      "field": "title"
    }
  ]
}

Obter Vaga por ID ​

Recupera os detalhes completos de uma vaga, incluindo empresa, departamento, localidade, pipeline, responsáveis e as perguntas configuradas (atsJobQuestions).

http
GET /v1/ats/user/jobs/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da vaga.

Exemplo de Requisição ​

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

Respostas ​

200 OK

Retorna a vaga com seus relacionamentos e perguntas.

json
{
  "id": 1,
  "atsId": 1,
  "atsCompanyId": 1,
  "atsPipelineId": 1,
  "atsDepartmentId": 1,
  "atsLocationId": 1,
  "atsUserId": 1,
  "atsHiringUserId": 1,
  "code": "REQ-2026-001",
  "title": "Desenvolvedor Full Stack Pleno",
  "slug": "desenvolvedor-full-stack-pleno",
  "description": "## Sobre a vaga\n\nBuscamos um desenvolvedor full stack para atuar no produto principal da empresa.",
  "requirements": "- Experiência sólida com Node.js e TypeScript\n- Vivência com PostgreSQL e Redis",
  "benefits": "- Vale-refeição de R$ 880\n- Plano de saúde e odontológico",
  "status": "draft",
  "employmentType": "full_time",
  "workplaceType": "hybrid",
  "seniority": "mid",
  "openings": 2,
  "salaryMin": "8000.00",
  "salaryMax": "12000.00",
  "salaryCurrency": "BRL",
  "salaryPeriod": "month",
  "salaryIsPublic": true,
  "metadata": {
    "area": "Engenharia",
    "prioridade": "alta"
  },
  "publishedAt": null,
  "closesAt": "2026-10-15T00:00:00.000Z",
  "closedAt": null,
  "createdAt": "2026-09-10T16:08:24.207+00:00",
  "updatedAt": "2026-09-10T16:08:24.207+00:00",
  "atsCompany": {
    "id": 1,
    "name": "Catho"
  },
  "atsLocation": {
    "id": 1,
    "name": "Av. Dr. Luís Rocha Miranda"
  },
  "atsPipeline": {
    "id": 1,
    "name": "Default"
  },
  "atsUser": {
    "id": 1,
    "firstName": "Gerson",
    "lastName": "Tavares",
    "email": "gerson_tavares@live.com"
  },
  "atsHiringUser": {
    "id": 1,
    "firstName": "Gerson",
    "lastName": "Tavares",
    "email": "gerson_tavares@live.com"
  },
  "atsJobQuestions": [],
  "atsDepartment": {
    "id": 1,
    "name": "I.T"
  }
}

404 Not Found

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

Atualizar Vaga ​

Atualiza os dados de uma vaga existente. Se o título for alterado, o slug é regenerado automaticamente.

http
PUT /v1/ats/user/jobs/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da vaga.

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais — envie apenas o que deseja alterar.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/jobs/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Desenvolvedor Full Stack Sênior",
    "seniority": "senior",
    "salaryMin": 12000,
    "salaryMax": 18000
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

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

Alterar Status da Vaga ​

Altera o status da vaga, controlando sua visibilidade no job board. O ciclo de status é: draft → open → paused → closed → archived.

As datas de publicação e fechamento são gerenciadas automaticamente:

  • Ao sair de draft pela primeira vez, publishedAt é preenchido com a data atual;
  • Ao mudar para closed, closedAt é preenchido;
  • Ao reabrir uma vaga fechada (open ou paused), closedAt é limpo.
http
PATCH /v1/ats/user/jobs/:id/status

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da vaga.

Payload (Body) ​

AtributoTipoObrigatórioDescrição
statusenumSimNovo status: draft, open, paused, closed ou archived.

Exemplo de Requisição ​

bash
curl -X PATCH "https://api.us.basis.tavares.in/v1/ats/user/jobs/1/status" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "open"
  }'

Respostas ​

204 No Content

Status alterado com sucesso.

422 Unprocessable Entity

Erro de validação — o status informado não é um valor válido.

json
{
  "errors": [
    {
      "message": "Status inválido",
      "rule": "enum",
      "field": "status"
    }
  ]
}

Remover Vaga ​

Exclui uma vaga da instância.

http
DELETE /v1/ats/user/jobs/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da vaga.

Exemplo de Requisição ​

bash
curl -X DELETE "https://api.us.basis.tavares.in/v1/ats/user/jobs/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 vaga não existe na instância.

Perguntas da Vaga ​

Cada vaga pode ter perguntas personalizadas que o candidato responde ao se candidatar no job board. As perguntas são exibidas na ordem definida pelo campo position e suportam diferentes tipos de resposta:

TipoDescrição
short_textTexto curto (uma linha).
long_textTexto longo (múltiplas linhas).
single_choiceEscolha única entre as options.
multi_choiceMúltipla escolha entre as options.
booleanSim ou não.
numberValor numérico.
dateData.
fileUpload de arquivo.
urlEndereço web (ex.: link de portfólio).

Perguntas eliminatórias (knockout)

O campo knockout define a resposta que elimina automaticamente o candidato — por exemplo, { "operator": "equals", "value": "Não" } em uma pergunta booleana. Essa configuração é interna do processo seletivo e nunca é exposta publicamente no job board: o candidato não sabe qual resposta o eliminaria.

Listar Perguntas ​

Lista as perguntas de uma vaga, ordenadas por position.

http
GET /v1/ats/user/jobs/:jobId/questions

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
jobIdnumberSimO ID da vaga.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/jobs/1/questions" \
  -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 perguntas da vaga.

json
[
  {
    "id": 1,
    "atsId": 1,
    "atsJobId": 1,
    "label": "Você tem experiência com TypeScript?",
    "helpText": "Considere experiência profissional ou em projetos pessoais relevantes.",
    "type": "single_choice",
    "options": [
      "Sim, mais de 3 anos",
      "Sim, entre 1 e 3 anos",
      "Não, mas tenho interesse"
    ],
    "isRequired": true,
    "knockout": {
      "value": "Sim, mais de 3 anos",
      "operator": "equals"
    },
    "position": 1,
    "createdAt": "2026-09-11T02:28:28.396+00:00",
    "updatedAt": "2026-09-11T02:28:28.396+00:00"
  }
]

Criar Pergunta ​

Adiciona uma nova pergunta à vaga.

http
POST /v1/ats/user/jobs/:jobId/questions

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
jobIdnumberSimO ID da vaga.

Payload (Body) ​

AtributoTipoObrigatórioDescrição
labelstringSimTexto da pergunta (máx. 250 caracteres).
helpTextstringNãoTexto de ajuda exibido ao candidato (máx. 500 caracteres).
typeenumSimTipo da resposta (ver tabela de tipos acima).
optionsstring[]NãoOpções de resposta (para single_choice e multi_choice).
isRequiredbooleanNãoIndica se a resposta é obrigatória.
knockoutobjectNãoResposta eliminatória, ex.: { "operator": "equals", "value": "..." }.
positionnumberNãoPosição de exibição (mínimo: 0).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/jobs/1/questions" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Você tem experiência com TypeScript?",
    "helpText": "Considere experiência profissional ou em projetos pessoais relevantes.",
    "type": "single_choice",
    "options": ["Sim, mais de 3 anos", "Sim, entre 1 e 3 anos", "Não, mas tenho interesse"],
    "isRequired": true,
    "knockout": {
      "operator": "equals",
      "value": "Sim, mais de 3 anos"
    },
    "position": 1
  }'

Respostas ​

201 Created

Retorna o ID da pergunta criada.

json
{
  "id": 1
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json
{
  "errors": [
    {
      "message": "Rótulo é obrigatório",
      "rule": "required",
      "field": "label"
    }
  ]
}

Atualizar Pergunta ​

Atualiza uma pergunta existente, incluindo sua posição na ordenação.

http
PUT /v1/ats/user/jobs/:jobId/questions/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
jobIdnumberSimO ID da vaga.
idnumberSimO ID da pergunta.

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais — envie apenas o que deseja alterar.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/jobs/1/questions/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Qual sua experiência com TypeScript?",
    "isRequired": true,
    "position": 2
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando a vaga ou a pergunta não existe na instância.

Remover Pergunta ​

Remove uma pergunta da vaga.

http
DELETE /v1/ats/user/jobs/:jobId/questions/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
jobIdnumberSimO ID da vaga.
idnumberSimO ID da pergunta.

Exemplo de Requisição ​

bash
curl -X DELETE "https://api.us.basis.tavares.in/v1/ats/user/jobs/1/questions/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 vaga ou a pergunta não existe na instância.