Basis

Appearance

Instâncias & Setup ​

Uma instância ATS é o ambiente de recrutamento da sua empresa dentro da plataforma: vagas, candidatos, pipelines e entrevistas vivem dentro dela. Antes de usar qualquer endpoint do ATS (/v1/ats/...), você precisa provisionar uma instância — e é isso que estes endpoints fazem.

A criação é mais do que um simples INSERT: em uma única transação, a plataforma cria a empresa padrão, o pipeline padrão com 6 etapas e o primeiro usuário staff com papel de owner, devolvendo as credenciais de acesso e o tokenHeader que identifica a instância em todas as chamadas seguintes.

Headers obrigatórios

Estes endpoints pertencem à área do dono da conta na plataforma. Todas as requisições exigem Authorization: Bearer {token} (autenticação da plataforma, guard user) e o parâmetro de query workspaceId com o ID do projeto. O header X-Ats-Id não é usado aqui — ele é o tokenHeader gerado na criação da instância. Limite de 100 requisições por minuto (429 ao exceder).

Estrutura de Dados Principal ​

Uma instância ATS contém as seguintes informações principais:

CampoTipoDescrição
nameStringNome da instância (máx. 160 caracteres).
slugStringSlug gerado automaticamente a partir do nome.
tokenHeaderStringUUID que identifica a instância — usado como X-Ats-Id nas APIs /v1/ats/**.
defaultLocaleStringLocale padrão (padrão: pt).
timezoneStringFuso horário da instância (padrão: UTC).
currencyStringMoeda padrão, 3 letras (padrão: BRL).
retentionDaysNumberDias de retenção de dados (30 a 3650, padrão: 730).
isActiveBooleanIndica se a instância está ativa.
workspaceStorageIdNumberProvedor de armazenamento do projeto (nulo se não vinculado).
workspaceMailIdNumberProvedor de e-mail do projeto (nulo se não vinculado).

Setup Inicial ​

O POST /user/ats executa todo o provisionamento em uma única transação — se qualquer etapa falhar, nada é persistido:

  1. Empresa default: criada com o mesmo nome da instância e marcada como isDefault.
  2. Pipeline default: chamado Default, com as 6 etapas padrão na ordem New (applied), Screening, Interview, Offer, Hired e Rejected.
  3. Primeiro usuário staff: criado com o e-mail do usuário autenticado na plataforma e vinculado como owner da empresa default.
  4. Resposta 201: inclui email, password (senha temporária, exibida uma única vez) e tokenHeader.

Guarde a senha temporária e o tokenHeader imediatamente — eles não podem ser recuperados depois (o token pode ser regerado, a senha não).

Endpoints ​

Listar Instâncias ​

Lista as instâncias ATS do projeto, com paginação e busca por nome.

http
GET /user/ats

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
workspaceIdnumberSimID do projeto (workspace) ao qual a instância pertence.
pagenumberNãoO número da página (mínimo: 1).
perPagenumberNãoItens por página (entre 1 e 100, padrão: 25).
searchstringNãoBusca por termo no nome da instância (máx. 150 caracteres).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/user/ats?workspaceId=1&page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna um objeto de paginação contendo a lista de instâncias, ordenadas da mais recente para a mais antiga.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "2",
      "name": "Hiring Board",
      "slug": "hiring-board",
      "tokenHeader": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    },
    {
      "id": "1",
      "name": "Recruiting Hub",
      "slug": "recruiting-hub",
      "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "isActive": true,
      "createdAt": "2026-09-01T10:05:33.000+00:00",
      "updatedAt": "2026-09-01T10:05:33.000+00:00"
    }
  ]
}

403 Forbidden

Ocorre quando o workspaceId não é informado ou o projeto pertence a outro usuário.

json
{
  "notice": "O projeto precisa ser informado",
  "field": "workspaceId"
}

Criar Instância ​

Provisiona uma nova instância ATS, executando o setup inicial completo em transação.

http
POST /user/ats

Payload (Body) ​

AtributoTipoObrigatórioDescrição
ats.namestringSimNome da instância (máx. 160 caracteres).
ats.workspaceStorageIdnumberNãoID do provedor de armazenamento do projeto (deve existir e estar ativo).
ats.workspaceMailIdnumberNãoID do provedor de e-mail do projeto (deve existir e estar ativo).
ats.defaultLocalestringNãoLocale padrão (máx. 10 caracteres, padrão: pt).
ats.timezonestringNãoFuso horário (máx. 64 caracteres, padrão: UTC).
ats.currencystringNãoMoeda padrão, exatamente 3 caracteres (padrão: BRL).
ats.retentionDaysnumberNãoDias de retenção de dados (mín. 30, máx. 3650, padrão: 730).
ats.isActivebooleanNãoIndica se a instância já nasce ativa (padrão: true).
workspaceDomainsnumber[]SimIDs dos domínios do projeto vinculados à instância (pode ser um array vazio).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/user/ats?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ats": {
      "name": "Acme Recruiting",
      "workspaceStorageId": null,
      "workspaceMailId": null
    },
    "workspaceDomains": [3]
  }'

Respostas ​

201 Created

Retorna as credenciais do primeiro usuário staff e o token da instância. A senha temporária é exibida uma única vez.

json
{
  "email": "maria@acme.com",
  "password": "a1b2c3d4",
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

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

Obter Instância por ID ​

Recupera os detalhes de uma instância, incluindo os domínios, o provedor de armazenamento e o provedor de e-mail vinculados.

http
GET /user/ats/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da instância.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/user/ats/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna a instância com workspaceDomains, workspaceStorage e workspaceMail.

json
{
  "id": "1",
  "workspaceId": "1",
  "workspaceMailId": null,
  "workspaceStorageId": null,
  "name": "Acme Recruiting",
  "slug": "acme-recruiting",
  "defaultLocale": "pt",
  "timezone": "UTC",
  "currency": "BRL",
  "retentionDays": 730,
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isActive": true,
  "createdAt": "2026-09-01T10:05:33.000+00:00",
  "updatedAt": "2026-09-01T10:05:33.000+00:00",
  "deletedAt": null,
  "workspaceDomains": [
    {
      "id": "3",
      "uri": "show.local"
    }
  ],
  "workspaceStorage": null,
  "workspaceMail": null
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Atualizar Instância ​

Atualiza as configurações de uma instância e sincroniza os domínios vinculados.

http
PUT /user/ats/:id

Payload (Body) ​

Aceita os mesmos campos da criação: o objeto ats e o array workspaceDomains (que substitui os vínculos atuais).

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/user/ats/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ats": {
      "name": "Acme Talent",
      "isActive": false
    },
    "workspaceDomains": [3]
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Remover Instância ​

Remove uma instância via soft delete — o registro deixa de aparecer em qualquer consulta, mas não é apagado fisicamente.

http
DELETE /user/ats/:id

Exemplo de Requisição ​

bash
curl -X DELETE "https://api.us.basis.tavares.in/user/ats/1?workspaceId=1" \
  -H "Authorization: Bearer {token}"

Respostas ​

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Listar para Dropdown ​

Retorna as instâncias em formato simplificado (value/label), ideal para selects no frontend.

http
GET /user/ats/list

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
workspaceIdnumberSimID do projeto (workspace).
searchstringNãoBusca por termo no nome da instância (máx. 150 caracteres).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/user/ats/list?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna um array com as instâncias ordenadas por nome.

json
[
  {
    "value": 1,
    "label": "Alpha ATS"
  },
  {
    "value": 2,
    "label": "Beta ATS"
  }
]

Regerar Token da Instância ​

Gera um novo tokenHeader (UUID) para a instância. O token anterior deixa de ser válido imediatamente — todas as integrações que usam o header X-Ats-Id precisam ser atualizadas.

http
PATCH /user/ats/:id/change-token

Exemplo de Requisição ​

bash
curl -X PATCH "https://api.us.basis.tavares.in/user/ats/1/change-token?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna o novo token da instância.

json
{
  "tokenHeader": "9b2f7c1e-4d3a-4e5f-8a6b-1c2d3e4f5a6b"
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.