Basis

Appearance

Entrevistas ​

As entrevistas registram os encontros entre o time e os candidatos ao longo do funil de recrutamento. Cada entrevista pertence a uma candidatura (atsApplicationId) e a uma etapa do pipeline (atsStageId), tem período de início e fim, e uma lista de participantes do time.

Enquanto a listagem e o detalhe permitem acompanhar todas as entrevistas da instância (respeitando o escopo de empresas do usuário), a agenda retorna as próximas entrevistas do usuário logado. A escrita (criar, atualizar, remover) exige papel de gestão (owner/admin/manager) ou interviewer na empresa da vaga.

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} (guard atsUser).

Estrutura de Dados Principal ​

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

CampoTipoDescrição
atsApplicationIdNumberID da candidatura à qual a entrevista pertence.
atsStageIdNumberID da etapa do pipeline associada.
titleStringTítulo da entrevista (máx. 200 caracteres).
modeEnumFormato: onsite (presencial), video ou phone.
statusEnumSituação: scheduled, confirmed, completed, canceled ou no_show.
startsAt / endsAtDateTimeInício e término (endsAt deve ser posterior a startsAt).
timezoneStringFuso horário (ex.: America/Sao_Paulo).
locationStringLocal físico (entrevistas presenciais).
meetingUrlStringLink da reunião (entrevistas por vídeo/telefone).
notesStringObservações internas sobre a entrevista.
participantsArrayParticipantes do time: [{ atsUserId, isOrganizer? }] (mínimo 1).

Listar Entrevistas ​

Lista as entrevistas da instância, com paginação e filtros por candidatura, status e período. Usuários sem papel de admin veem apenas entrevistas das empresas às quais têm acesso.

http
GET /v1/ats/user/interviews

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).
atsApplicationIdnumberNãoFiltra por candidatura.
statusenumNãoFiltra por status: scheduled, confirmed, completed, canceled ou no_show.
fromdateNãoInício do período (YYYY-MM-DD).
todateNãoFim do período (YYYY-MM-DD).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/interviews?status=scheduled&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 entrevistas.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "atsId": 1,
      "atsApplicationId": 1,
      "atsStageId": 1,
      "title": "Entrevista técnica - Desenvolvedor Full Stack Pleno",
      "mode": "video",
      "status": "scheduled",
      "startsAt": "2026-09-15T14:00:00.000Z",
      "endsAt": "2026-09-15T15:00:00.000Z",
      "timezone": "America/Sao_Paulo",
      "location": "Av. Dr. Luís Rocha Miranda, São Paulo - SP",
      "meetingUrl": "https://meet.google.com/abc-defg-hij",
      "createdAt": "2026-09-11T03:20:25.676+00:00",
      "updatedAt": "2026-09-11T03:20:25.676+00:00"
    }
  ]
}

Agenda do Usuário Logado ​

Retorna as próximas entrevistas do usuário autenticado — aquelas em que ele é participante, com status scheduled ou confirmed. Ideal para telas de "minha agenda".

http
GET /v1/ats/user/interviews/agenda

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
fromdateNãoInício do período (YYYY-MM-DD).
todateNãoFim do período (YYYY-MM-DD).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/interviews/agenda?from=2026-09-01&to=2026-10-31" \
  -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 próximas entrevistas do usuário logado.

json
[
  {
    "id": 2,
    "atsId": 1,
    "atsApplicationId": 1,
    "atsStageId": 1,
    "title": "Entrevista técnica - Desenvolvedor Full Stack Pleno",
    "mode": "video",
    "status": "scheduled",
    "startsAt": "2026-09-15T14:00:00.000Z",
    "endsAt": "2026-09-15T15:00:00.000Z",
    "timezone": "America/Sao_Paulo",
    "location": "Av. Dr. Luís Rocha Miranda, São Paulo - SP",
    "meetingUrl": "https://meet.google.com/abc-defg-hij"
  }
]

Criar Entrevista ​

Agenda uma nova entrevista para uma candidatura. A lista de participantes é obrigatória (mínimo 1) e endsAt deve ser posterior a startsAt.

http
POST /v1/ats/user/interviews

Payload (Body) ​

AtributoTipoObrigatórioDescrição
atsApplicationIdnumberSimID da candidatura (deve existir na instância).
atsStageIdnumberSimID da etapa do pipeline (deve existir na instância).
titlestringSimTítulo da entrevista (máx. 200 caracteres).
modeenumNãoFormato: onsite, video ou phone.
startsAtdatetimeSimData e hora de início.
endsAtdatetimeSimData e hora de término (posterior a startsAt).
timezonestringNãoFuso horário (máx. 64 caracteres).
locationstringNãoLocal físico (máx. 255 caracteres).
meetingUrlstringNãoLink da reunião (máx. 500 caracteres).
notesstringNãoObservações internas.
participantsarraySimParticipantes: [{ atsUserId, isOrganizer? }] (mínimo 1; atsUserId deve existir na instância).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/interviews" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "atsApplicationId": 1,
    "atsStageId": 1,
    "title": "Entrevista técnica - Desenvolvedor Full Stack Pleno",
    "mode": "video",
    "startsAt": "2026-09-15 14:00:00",
    "endsAt": "2026-09-15 15:00:00",
    "timezone": "America/Sao_Paulo",
    "location": "Av. Dr. Luís Rocha Miranda, São Paulo - SP",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "notes": "Entrevista técnica focada em Node.js, TypeScript e modelagem de banco de dados. Preparar exercício prático de pair programming.",
    "participants": [
      {
        "atsUserId": 1,
        "isOrganizer": true
      },
      {
        "atsUserId": 2,
        "isOrganizer": false
      }
    ]
  }'

Respostas ​

201 Created

Retorna o ID da entrevista criada.

json
{
  "id": 1
}

422 Unprocessable Entity

Ocorre quando endsAt não é posterior a startsAt (INVALID_PERIOD) ou quando há erro de validação nos campos enviados.

json
{
  "message": "A data de término deve ser posterior à data de início",
  "code": "INVALID_PERIOD"
}

403 Forbidden

Ocorre quando o usuário não tem papel de gestão ou interviewer na empresa da vaga.

json
{
  "message": "Você não tem permissão para realizar esta ação",
  "code": "FORBIDDEN"
}

Obter Entrevista por ID ​

Recupera os detalhes de uma entrevista, incluindo participantes (com dados do usuário), candidatura, candidato e vaga.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da entrevista.

Exemplo de Requisição ​

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

Respostas ​

200 OK

Retorna a entrevista com atsInterviewUsers (participantes) e atsApplication (candidatura com candidato e vaga).

json
{
  "id": 1,
  "atsId": 1,
  "atsApplicationId": 1,
  "atsStageId": 1,
  "title": "Entrevista técnica - Desenvolvedor Full Stack Pleno",
  "mode": "video",
  "status": "scheduled",
  "startsAt": "2026-09-15T14:00:00.000Z",
  "endsAt": "2026-09-15T15:00:00.000Z",
  "timezone": "America/Sao_Paulo",
  "location": "Av. Dr. Luís Rocha Miranda, São Paulo - SP",
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "notes": "Entrevista técnica focada em Node.js, TypeScript e modelagem de banco de dados. Preparar exercício prático de pair programming.",
  "createdAt": "2026-09-11T03:20:25.676+00:00",
  "updatedAt": "2026-09-11T03:20:25.676+00:00",
  "atsInterviewUsers": [
    {
      "id": 1,
      "atsId": 1,
      "atsInterviewId": 1,
      "atsUserId": 1,
      "isOrganizer": true,
      "createdAt": "2026-09-11T03:20:25.722+00:00",
      "updatedAt": "2026-09-11T03:20:25.722+00:00",
      "deletedAt": null,
      "atsUser": {
        "id": 1,
        "firstName": "John",
        "lastName": "Doe (updated)",
        "email": "gerson_tavares@live.com",
        "avatarUrl": null
      }
    },
    {
      "id": 2,
      "atsId": 1,
      "atsInterviewId": 1,
      "atsUserId": 2,
      "isOrganizer": false,
      "createdAt": "2026-09-11T03:20:25.737+00:00",
      "updatedAt": "2026-09-11T03:20:25.737+00:00",
      "deletedAt": null,
      "atsUser": {
        "id": 2,
        "firstName": "John",
        "lastName": "Doe",
        "email": "johndoe@gmail.com",
        "avatarUrl": null
      }
    }
  ],
  "atsApplication": {
    "id": 1,
    "atsCandidateId": 1,
    "atsJobId": 1,
    "atsCandidate": {
      "id": 1,
      "firstName": "Maria",
      "lastName": "Silva",
      "email": "maria.silva@email.com",
      "headline": "Desenvolvedora Full Stack Plena"
    },
    "atsJob": {
      "id": 1,
      "title": "Desenvolvedor Full Stack Pleno",
      "atsCompanyId": 1
    }
  }
}

404 Not Found

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

Atualizar Entrevista ​

Atualiza os dados de uma entrevista existente. Se participants for enviado, a lista é sincronizada — substituída integralmente pelo novo conjunto. A regra endsAt > startsAt também é validada na atualização, combinando os valores enviados com os já registrados.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da entrevista.

Payload (Body) ​

Aceita os mesmos campos da criação, todos opcionais: atsStageId, title, mode, status, startsAt, endsAt, timezone, location, meetingUrl, notes e participants.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/interviews/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "atsStageId": 1,
    "title": "Entrevista técnica - Desenvolvedor Full Stack Pleno (remarcada)",
    "mode": "video",
    "status": "confirmed",
    "startsAt": "2026-09-16 10:00:00",
    "endsAt": "2026-09-16 11:00:00",
    "timezone": "America/Sao_Paulo",
    "location": "Av. Dr. Luís Rocha Miranda, São Paulo - SP",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "notes": "Entrevista remarcada a pedido do candidato. Confirmar presença na véspera.",
    "participants": [
      {
        "atsUserId": 1,
        "isOrganizer": true
      },
      {
        "atsUserId": 2,
        "isOrganizer": false
      }
    ]
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o período resultante é inválido (INVALID_PERIOD) ou quando há erro de validação nos campos enviados.

json
{
  "message": "A data de término deve ser posterior à data de início",
  "code": "INVALID_PERIOD"
}

Remover Entrevista ​

Exclui uma entrevista da instância.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da entrevista.

Exemplo de Requisição ​

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