Pipelines & Etapas

Os pipelines representam os funis de recrutamento da sua instância do ATS. Cada pipeline é uma sequência ordenada de etapas — da inscrição do candidato até a contratação ou recusa — e as vagas são vinculadas a um pipeline para definir por qual funil suas candidaturas vão passar.

Você pode manter o pipeline padrão criado na ativação da instância ou montar funis personalizados para diferentes tipos de vaga. Ao criar um pipeline, ele já nasce com as 6 etapas padrão (New, Screening, Interview, Offer, Hired, Rejected), prontas para uso — e você pode renomeá-las, adicionar novas etapas e reordená-las livremente.

Headers obrigatórios

Todas as requisições devem incluir o header X-Ats-Id (UUID) com o identificador da instância (tokenHeader) e Authorization: Bearer {token} com o token do staff (guard atsUser). As operações de escrita (criar, atualizar, reordenar e remover) exigem perfil de administrador (owner ou admin); demais perfis recebem 403 Forbidden.

---

Estrutura de Dados Principal

Um pipeline contém as seguintes informações:

Campo	Tipo	Descrição
name	String	Nome do pipeline (máx. 160 caracteres).
isDefault	Boolean	Indica se é o pipeline padrão da instância.
isEnforceSequential	Boolean	Quando true, impede que candidaturas pulem etapas no funil.
atsStages	Array	Etapas do pipeline, ordenadas por position (no detalhe e na listagem).

Cada etapa contém:

Campo	Tipo	Descrição
name	String	Nome da etapa (máx. 150 caracteres).
slug	String	Slug gerado automaticamente a partir do nome.
type	Enum	Tipo da etapa: applied, screening, assessment, interview, offer, hired ou rejected.
position	Number	Posição da etapa no funil (a partir de 1).
isTerminal	Boolean	Derivado automaticamente: true para etapas do tipo hired e rejected.

Regras do funil

• O primeiro pipeline criado na instância é sempre o padrão (isDefault: true). Ao marcar outro pipeline como padrão, o anterior é desmarcado automaticamente — existe sempre um único pipeline default.
• Cada pipeline pode ter apenas uma etapa do tipo applied (a etapa de entrada das candidaturas). Tentativas de criar ou promover uma segunda etapa applied falham com 422 APPLIED_STAGE_EXISTS.
• A etapa applied não pode ser removida (422 APPLIED_STAGE_LOCKED), e nenhuma etapa pode ser removida enquanto houver candidaturas vinculadas a ela (422 STAGE_IN_USE).

---

Pipelines

Listar Pipelines

Lista os pipelines da instância com paginação, incluindo as etapas de cada um em atsStages (ordenadas por position).

GET /v1/ats/user/pipelines

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).
orderBy	enum	Não	Ordena por id, name ou createdAt.
orderDirection	enum	Não	Direção da ordenação: asc ou desc.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/pipelines?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 os pipelines e suas etapas.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "atsId": 1,
      "name": "Default",
      "isDefault": true,
      "isEnforceSequential": false,
      "createdAt": "2026-09-10T02:10:58.799+00:00",
      "updatedAt": "2026-09-10T02:10:58.799+00:00",
      "atsStages": [
        {
          "id": 1,
          "atsPipelineId": 1,
          "name": "New",
          "slug": "new",
          "type": "applied",
          "position": 1,
          "isTerminal": false
        },
        {
          "id": 2,
          "atsPipelineId": 1,
          "name": "Screening",
          "slug": "screening",
          "type": "screening",
          "position": 2,
          "isTerminal": false
        },
        {
          "id": 3,
          "atsPipelineId": 1,
          "name": "Interview",
          "slug": "interview",
          "type": "interview",
          "position": 3,
          "isTerminal": false
        },
        {
          "id": 4,
          "atsPipelineId": 1,
          "name": "Offer",
          "slug": "offer",
          "type": "offer",
          "position": 4,
          "isTerminal": false
        },
        {
          "id": 5,
          "atsPipelineId": 1,
          "name": "Hired",
          "slug": "hired",
          "type": "hired",
          "position": 5,
          "isTerminal": true
        },
        {
          "id": 6,
          "atsPipelineId": 1,
          "name": "Rejected",
          "slug": "rejected",
          "type": "rejected",
          "position": 6,
          "isTerminal": true
        }
      ]
    }
  ]
}

Listar Pipelines (Lista Simples)

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

GET /v1/ats/user/pipelines/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
search	string	Não	Busca por termo no início do nome (máx. 150 caracteres).

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/pipelines/list" \
  -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 pipelines em formato value/label.

[
  {
    "value": 1,
    "label": "Default"
  }
]

Criar Pipeline

Cria um novo pipeline já com as 6 etapas padrão (New, Screening, Interview, Offer, Hired, Rejected). Se for o primeiro pipeline da instância, ele se torna o padrão automaticamente.

POST /v1/ats/user/pipelines

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do pipeline (máx. 160 caracteres).
isDefault	boolean	Não	Define o pipeline como padrão da instância (desmarca o padrão atual).
isEnforceSequential	boolean	Não	Quando true, impede que candidaturas pulem etapas (padrão: false).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/pipelines" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Avaliation",
    "isDefault": false,
    "isEnforceSequential": true
  }'

Respostas

201 Created

Retorna o ID do pipeline criado.

{
  "id": 2
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

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

403 Forbidden

Ocorre quando o usuário autenticado não possui perfil de administrador (owner ou admin).

Obter Pipeline por ID

Recupera os detalhes de um pipeline, incluindo suas etapas ordenadas por position.

GET /v1/ats/user/pipelines/:id

Parâmetros de Rota

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

Exemplo de Requisição

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

Respostas

200 OK

Retorna o pipeline com suas etapas em atsStages.

{
  "id": 1,
  "atsId": 1,
  "name": "Default",
  "isDefault": true,
  "isEnforceSequential": false,
  "createdAt": "2026-09-10T02:10:58.799+00:00",
  "updatedAt": "2026-09-10T02:10:58.799+00:00",
  "atsStages": [
    {
      "id": 1,
      "atsPipelineId": 1,
      "name": "New",
      "slug": "new",
      "type": "applied",
      "position": 1,
      "isTerminal": false
    },
    {
      "id": 5,
      "atsPipelineId": 1,
      "name": "Hired",
      "slug": "hired",
      "type": "hired",
      "position": 5,
      "isTerminal": true
    }
  ]
}

404 Not Found

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

Atualizar Pipeline

Atualiza os dados de um pipeline existente.

PUT /v1/ats/user/pipelines/:id

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do pipeline (máx. 160 caracteres).
isDefault	boolean	Não	Define o pipeline como padrão da instância.
isEnforceSequential	boolean	Não	Habilita ou desabilita a progressão sequencial no funil.

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/pipelines/2" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Avaliation",
    "isDefault": false,
    "isEnforceSequential": true
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Erro de validação nos campos enviados.

Definir Pipeline como Padrão

Marca um pipeline como o padrão da instância, desmarcando o pipeline padrão anterior. Existe sempre um único pipeline default por instância.

PATCH /v1/ats/user/pipelines/:id/default

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
id	number	Sim	O ID do pipeline que se tornará o padrão.

Exemplo de Requisição

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

Respostas

204 No Content

Pipeline definido como padrão com sucesso.

Remover Pipeline

Exclui um pipeline da instância (exclusão lógica).

DELETE /v1/ats/user/pipelines/:id

Exemplo de Requisição

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

Respostas

204 No Content

Remoção concluída com sucesso.

---

Etapas

As etapas definem o fluxo de um pipeline. Cada etapa possui um type que indica sua função no funil — as etapas do tipo hired e rejected são terminais (o sistema deriva isTerminal automaticamente), enquanto a etapa applied é a entrada obrigatória das candidaturas.

Listar Etapas

Lista as etapas de um pipeline, ordenadas por position (use orderDirection para inverter), com paginação e busca.

GET /v1/ats/user/pipelines/:pipelineId/stages

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
pipelineId	number	Sim	O ID do pipeline.

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).
orderDirection	enum	Não	Direção da ordenação por position: asc (padrão) ou desc.

Exemplo de Requisição

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/pipelines/1/stages" \
  -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 as etapas do pipeline.

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "atsId": 1,
      "atsPipelineId": 1,
      "name": "New",
      "slug": "new",
      "type": "applied",
      "position": 1,
      "isTerminal": false,
      "createdAt": "2026-09-10T02:10:58.814+00:00",
      "updatedAt": "2026-09-10T02:10:58.814+00:00"
    },
    {
      "id": 2,
      "atsId": 1,
      "atsPipelineId": 1,
      "name": "Screening",
      "slug": "screening",
      "type": "screening",
      "position": 2,
      "isTerminal": false,
      "createdAt": "2026-09-10T02:10:58.840+00:00",
      "updatedAt": "2026-09-10T02:10:58.840+00:00"
    },
    {
      "id": 3,
      "atsId": 1,
      "atsPipelineId": 1,
      "name": "Interview",
      "slug": "interview",
      "type": "interview",
      "position": 3,
      "isTerminal": false,
      "createdAt": "2026-09-10T02:10:58.853+00:00",
      "updatedAt": "2026-09-10T02:10:58.853+00:00"
    }
  ]
}

422 Unprocessable Entity

Ocorre quando o pipelineId não pertence à instância.

Criar Etapa

Adiciona uma nova etapa ao pipeline. Se position for omitida, a etapa é criada na próxima posição disponível (ao final do funil).

POST /v1/ats/user/pipelines/:pipelineId/stages

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da etapa (máx. 150 caracteres). O slug é gerado automaticamente.
type	enum	Sim	Tipo da etapa: applied, screening, assessment, interview, offer, hired ou rejected.
position	number	Não	Posição da etapa no funil (mínimo: 1). Omitida, assume a próxima posição disponível.

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/pipelines/1/stages" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review of Rejection",
    "type": "rejected",
    "position": 1
  }'

Respostas

201 Created

Retorna o ID da etapa criada.

{
  "id": 21
}

422 Unprocessable Entity

Erro de validação nos campos enviados, ou tentativa de criar uma segunda etapa do tipo applied no pipeline.

{
  "message": "Já existe uma etapa de entrada (applied) neste pipeline",
  "code": "APPLIED_STAGE_EXISTS"
}

403 Forbidden

Ocorre quando o usuário autenticado não possui perfil de administrador (owner ou admin).

Obter Etapa por ID

Recupera os detalhes de uma etapa do pipeline.

GET /v1/ats/user/pipelines/:pipelineId/stages/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
pipelineId	number	Sim	O ID do pipeline.
id	number	Sim	O ID da etapa.

Exemplo de Requisição

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

Respostas

200 OK

Retorna os dados da etapa.

{
  "id": 20,
  "atsId": 1,
  "atsPipelineId": 1,
  "name": "Review of Rejection",
  "slug": "review-of-rejection",
  "type": "rejected",
  "position": 1,
  "isTerminal": true,
  "createdAt": "2026-09-10T15:18:39.229+00:00",
  "updatedAt": "2026-09-10T15:18:39.229+00:00"
}

404 Not Found

Ocorre quando a etapa não existe no pipeline informado.

Atualizar Etapa

Atualiza o nome e/ou o tipo de uma etapa. Ao alterar o nome, o slug é recalculado automaticamente. Para alterar a posição, utilize o endpoint de reordenação.

PUT /v1/ats/user/pipelines/:pipelineId/stages/:id

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
name	string	Não	Nome da etapa (máx. 150 caracteres).
type	enum	Não	Tipo da etapa: applied, screening, assessment, interview, offer, hired ou rejected.

Exemplo de Requisição

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/pipelines/1/stages/20" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review of Rejection (updated)",
    "type": "rejected"
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Erro de validação nos campos enviados, ou tentativa de promover a etapa a applied quando já existe uma etapa de entrada no pipeline (APPLIED_STAGE_EXISTS).

{
  "message": "Já existe uma etapa de entrada (applied) neste pipeline",
  "code": "APPLIED_STAGE_EXISTS"
}

Reordenar Etapas

Redefine a ordem das etapas do pipeline. A lista ids deve conter todos os IDs das etapas do pipeline, na nova ordem — listas parciais ou com IDs inválidos são rejeitadas.

POST /v1/ats/user/pipelines/:pipelineId/stages/reorder

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
ids	number[]	Sim	Lista completa dos IDs das etapas do pipeline, na nova ordem desejada.

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/pipelines/1/stages/reorder" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [1, 2, 3, 4, 6, 5]
  }'

Respostas

204 No Content

Reordenação concluída com sucesso.

422 Unprocessable Entity

A lista informada não corresponde exatamente às etapas do pipeline (IDs faltando, sobrando ou inexistentes).

{
  "message": "A lista de etapas informada não corresponde às etapas do pipeline",
  "code": "INVALID_STAGE_IDS"
}

Remover Etapa

Exclui uma etapa do pipeline (exclusão lógica). A etapa de entrada (applied) não pode ser removida, assim como qualquer etapa que possua candidaturas vinculadas.

DELETE /v1/ats/user/pipelines/:pipelineId/stages/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
pipelineId	number	Sim	O ID do pipeline.
id	number	Sim	O ID da etapa.

Exemplo de Requisição

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

Respostas

204 No Content

Remoção concluída com sucesso.

422 Unprocessable Entity

Tentativa de remover a etapa applied (APPLIED_STAGE_LOCKED) ou uma etapa em uso por candidaturas (STAGE_IN_USE).

{
  "message": "A etapa de entrada (applied) não pode ser removida",
  "code": "APPLIED_STAGE_LOCKED"
}

{
  "message": "Existem candidaturas vinculadas a esta etapa",
  "code": "STAGE_IN_USE"
}