Métricas

As métricas transformam os dados operacionais do ATS em indicadores acionáveis: quantas vagas estão abertas, quantos candidatos estão em andamento, quanto tempo leva para contratar e onde o funil trava. Com esses relatórios, a equipe de recrutamento identifica gargalos, compara períodos e prioriza as vagas que mais precisam de atenção.

Todos os endpoints desta página são de somente leitura (GET) e retornam arrays ou objetos prontos para alimentar dashboards e gráficos — sem paginação.

Headers obrigatórios

Todas as requisições devem incluir o header X-Ats-Id (UUID) com o identificador da instância e Authorization: Bearer {token} com o token de um usuário do ATS (atsUser). Endpoints de métricas não são públicos nem acessíveis a candidatos.

Filtros comuns e escopo por empresa

A maioria dos relatórios aceita os mesmos filtros opcionais de query:

Nome	Tipo	Obrigatório	Descrição
`from`	`string`	Não	Data inicial do período, no formato `YYYY-MM-DD`.
`to`	`string`	Não	Data final do período, no formato `YYYY-MM-DD`.
`atsJobId`	`number`	Não	Restringe o relatório a uma vaga específica.

O campo de data considerado depende do relatório: candidaturas usam appliedAt, contratações usam hiredAt, recusas usam rejectedAt e durações de etapa usam a data da transição.

Escopo RBAC por empresa

Administradores enxergam os dados de todas as empresas da instância. Recrutadores veem apenas as empresas às quais estão vinculados: um recrutador sem vínculos recebe contagens zeradas ou arrays vazios, nunca dados de outras empresas.

Endpoints

KPIs Gerais

Retorna os indicadores-chave do recrutamento em um único objeto, ideal para os cartões do topo de um dashboard.

http

GET /v1/ats/user/metrics/kpis

Parâmetros de Query

Aceita os filtros comuns: from, to e atsJobId.

Campos da Resposta

Campo	Tipo	Descrição
`openJobs`	`Number`	Quantidade de vagas com status `open`.
`activeApplications`	`Number`	Candidaturas com status `active` (em andamento no funil).
`newApplications`	`Number`	Candidaturas recebidas no período filtrado (todas, quando `from`/`to` não são informados).
`hired`	`Number`	Candidaturas contratadas no período filtrado.
`avgTimeToHireDays`	`Number \| null`	Tempo médio entre a candidatura e a contratação, em dias. `null` quando não há contratações.
`conversionRate`	`Number \| null`	Taxa de conversão: contratados ÷ candidaturas encerradas (status diferente de `active`). `null` quando não há candidaturas encerradas.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/metrics/kpis?from=2026-01-01&to=2026-09-10&atsJobId=1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o objeto com os seis KPIs.

json

{
  "openJobs": 2,
  "activeApplications": 0,
  "newApplications": 0,
  "hired": 0,
  "avgTimeToHireDays": null,
  "conversionRate": 0
}

Evolução de Candidaturas

Retorna uma série temporal com o total de candidaturas recebidas por período, ordenada da data mais antiga para a mais recente — a base para gráficos de linha ou área.

http

GET /v1/ats/user/metrics/applications

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`groupBy`	`enum`	Sim	Granularidade da série: `day`, `week` ou `month`.
`from`	`string`	Não	Data inicial do período (`YYYY-MM-DD`).
`to`	`string`	Não	Data final do período (`YYYY-MM-DD`).
`atsJobId`	`number`	Não	Restringe a série a uma vaga específica.

Cada ponto da série traz a data de início do período (date, no formato YYYY-MM-DD) e o total de candidaturas (applications).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/metrics/applications?groupBy=month&from=2026-01-01&to=2026-10-10&atsJobId=1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o array de pontos da série temporal.

json

[
  {
    "date": "2026-09-01",
    "applications": 1
  }
]

422 Unprocessable Entity

Ocorre quando groupBy não é enviado ou tem valor inválido.

json

{
  "errors": [
    {
      "message": "The groupBy field must be defined",
      "rule": "required",
      "field": "groupBy"
    }
  ]
}

Funil de uma Vaga

Retorna a contagem de candidaturas em cada etapa do pipeline de uma vaga, na ordem das etapas — o retrato instantâneo do funil. Etapas sem candidaturas aparecem com applicationsCount igual a zero, o que permite desenhar o funil completo mesmo quando vazio.

http

GET /v1/ats/user/metrics/funnel

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`atsJobId`	`number`	Sim	ID da vaga (deve existir na instância).

Campos da Resposta

Campo	Tipo	Descrição
`stageId`	`Number`	ID da etapa.
`stageName`	`String`	Nome da etapa.
`stageType`	`String`	Tipo da etapa (`applied`, `screening`, `interview`, `offer`, `hired`, `rejected`, etc.).
`position`	`Number`	Posição da etapa no pipeline.
`applicationsCount`	`Number`	Candidaturas atualmente nesta etapa.

Exemplo de Requisição

javascript

fetch('https://api.us.basis.tavares.in/v1/ats/user/metrics/funnel?atsJobId=1', {
  headers: {
    'X-Ats-Id': '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'Authorization': 'Bearer {token}'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Respostas

200 OK

Retorna o array de etapas com suas contagens, ordenado por position.

json

[
  {
    "stageId": 1,
    "stageName": "New",
    "stageType": "applied",
    "position": 1,
    "applicationsCount": 0
  },
  {
    "stageId": 2,
    "stageName": "Screening",
    "stageType": "screening",
    "position": 2,
    "applicationsCount": 0
  },
  {
    "stageId": 3,
    "stageName": "Interview",
    "stageType": "interview",
    "position": 3,
    "applicationsCount": 0
  },
  {
    "stageId": 4,
    "stageName": "Offer",
    "stageType": "offer",
    "position": 4,
    "applicationsCount": 0
  },
  {
    "stageId": 6,
    "stageName": "Rejected",
    "stageType": "rejected",
    "position": 5,
    "applicationsCount": 0
  },
  {
    "stageId": 5,
    "stageName": "Hired",
    "stageType": "hired",
    "position": 6,
    "applicationsCount": 1
  }
]

422 Unprocessable Entity

Ocorre quando atsJobId não é enviado ou a vaga não existe na instância.

json

{
  "errors": [
    {
      "message": "The selected atsJobId is invalid",
      "rule": "database.exists",
      "field": "atsJobId"
    }
  ]
}

Duração por Etapa

Retorna o tempo médio e mediano que as candidaturas permanecem em cada etapa, ordenado da etapa mais lenta para a mais rápida. É o relatório que revela os gargalos do funil: uma etapa com avgSeconds muito acima das demais indica onde os candidatos ficam parados.

Os tempos são calculados a partir do histórico de transições das candidaturas — cada mudança de etapa registra quantos segundos a candidatura passou na etapa de origem. Para entender como esse histórico é gerado a cada movimentação, consulte a página Candidaturas & Funil.

http

GET /v1/ats/user/metrics/stage-durations

Parâmetros de Query

Aceita os filtros comuns: from, to e atsJobId. O período filtra pela data em que a transição ocorreu.

Campos da Resposta

Campo	Tipo	Descrição
`stageId`	`Number`	ID da etapa de origem das transições.
`stageName`	`String`	Nome da etapa.
`transitions`	`Number`	Quantidade de saídas da etapa no período.
`avgSeconds`	`Number`	Tempo médio de permanência na etapa, em segundos.
`medianSeconds`	`Number`	Tempo mediano de permanência na etapa, em segundos (menos sensível a outliers que a média).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/metrics/stage-durations?from=2026-01-01&to=2026-09-12&atsJobId=1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o array de etapas com as estatísticas de tempo, ordenado por avgSeconds decrescente.

json

[
  {
    "stageId": 1,
    "stageName": "New",
    "transitions": 2,
    "avgSeconds": 1213,
    "medianSeconds": 1212
  }
]

Origens das Candidaturas

Retorna a distribuição das candidaturas por canal de origem, ordenada do canal com mais candidaturas para o com menos. Use para descobrir quais fontes de atração rendem mais volume.

http

GET /v1/ats/user/metrics/sources

Parâmetros de Query

Aceita os filtros comuns: from, to e atsJobId. O período filtra pela data da candidatura (appliedAt).

A source pode ser job_board, career_site, referral, sourced, import, agency ou other.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/metrics/sources?from=2026-01-01&to=2026-10-10&atsJobId=1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o array de origens com seus totais, ordenado por total decrescente.

json

[
  {
    "source": "career_site",
    "total": 1
  }
]

Motivos de Recusa

Retorna o ranking dos motivos de recusa mais frequentes, considerando apenas candidaturas rejected com motivo registrado. Use para entender por que os candidatos estão sendo eliminados e ajustar requisitos ou processos.

http

GET /v1/ats/user/metrics/rejection-reasons

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`limit`	`number`	Não	Quantidade máxima de motivos no ranking (entre 1 e 50, padrão: 10).
`from`	`string`	Não	Data inicial do período (`YYYY-MM-DD`), filtrando por `rejectedAt`.
`to`	`string`	Não	Data final do período (`YYYY-MM-DD`), filtrando por `rejectedAt`.
`atsJobId`	`number`	Não	Restringe o ranking a uma vaga específica.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/metrics/rejection-reasons?from=2026-01-01&to=2026-10-13&atsJobId=1&limit=10" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o array de motivos com seus totais, ordenado por total decrescente.

json

[
  {
    "reasonId": 1,
    "reasonName": "Salário fora do orçamento",
    "total": 1
  }
]

Métricas ​

Filtros comuns e escopo por empresa ​

Endpoints ​

KPIs Gerais ​

Parâmetros de Query ​

Campos da Resposta ​

Exemplo de Requisição ​

Respostas ​

Evolução de Candidaturas ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Funil de uma Vaga ​

Parâmetros de Query ​

Campos da Resposta ​

Exemplo de Requisição ​

Respostas ​

Duração por Etapa ​

Parâmetros de Query ​

Campos da Resposta ​

Exemplo de Requisição ​

Respostas ​

Origens das Candidaturas ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Motivos de Recusa ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Métricas

Filtros comuns e escopo por empresa

Endpoints

KPIs Gerais

Parâmetros de Query

Campos da Resposta

Exemplo de Requisição

Respostas

Evolução de Candidaturas

Parâmetros de Query

Exemplo de Requisição

Respostas

Funil de uma Vaga

Parâmetros de Query

Campos da Resposta

Exemplo de Requisição

Respostas

Duração por Etapa

Parâmetros de Query

Campos da Resposta

Exemplo de Requisição

Respostas

Origens das Candidaturas

Parâmetros de Query

Exemplo de Requisição

Respostas

Motivos de Recusa

Parâmetros de Query

Exemplo de Requisição

Respostas