Basis

Appearance

Localidades ​

As localidades representam os endereços físicos onde as vagas são oferecidas — um escritório, uma filial ou uma unidade da empresa. Cadastrá-las uma única vez permite reutilizá-las em quantas vagas forem necessárias, mantendo endereço, cidade, estado e coordenadas consistentes em todo o funil.

Além do CRUD de localidades, esta página documenta os endpoints de geografia — países, estados e cidades —, pensados para alimentar selects e formulários de endereço no painel.

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 do ATS (atsUser).

Estrutura de Dados Principal ​

Uma localidade contém as seguintes informações:

CampoTipoDescrição
nameStringNome ou endereço da localidade (máx. 200 caracteres).
cityStringCidade (máx. 200 caracteres, opcional).
stateStringEstado (máx. 200 caracteres, opcional).
countryStringPaís por extenso (máx. 200 caracteres, opcional).
countryCodeStringCódigo ISO do país com 2 letras (ex.: BR, opcional).
latitudeStringLatitude (entre -90 e 90, opcional).
longitudeStringLongitude (entre -180 e 180, opcional).

Permissões de escrita

Apenas usuários com papel owner, admin, recruiter ou hiring_manager podem criar, atualizar e remover localidades. Usuários com papel viewer recebem 403 Forbidden nas operações de escrita.

Localidades ​

Endpoints para gerenciamento das localidades reutilizáveis das vagas.

Listar Localidades ​

Lista as localidades da instância com paginação, busca e filtros por estado e país.

http
GET /v1/ats/user/locations

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 por termo no nome (máx. 150 caracteres).
statestringNãoFiltra por estado (máx. 200 caracteres).
countryCodestringNãoFiltra pelo código ISO do país (2 letras, ex.: BR).
orderByenumNãoOrdena por id, name ou createdAt.
orderDirectionenumNãoDireção da ordenação: asc ou desc.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/locations?page=1&perPage=25&countryCode=BR" \
  -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 localidades.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 2,
      "atsId": 1,
      "name": "R. Freire Farto, 70 - Jabaquara",
      "city": "São Paulo",
      "state": "São Paulo",
      "country": "Brazil",
      "countryCode": "BR",
      "latitude": "-23.6366600",
      "longitude": "-46.6454390",
      "createdAt": "2026-09-10T12:53:21.543+00:00",
      "updatedAt": "2026-09-10T12:53:21.543+00:00"
    },
    {
      "id": 1,
      "atsId": 1,
      "name": "Av. Dr. Luís Rocha Miranda",
      "city": "São Paulo",
      "state": "São Paulo",
      "country": "Brazil",
      "countryCode": "BR",
      "latitude": "-23.6361100",
      "longitude": "-46.6452859",
      "createdAt": "2026-09-10T12:52:48.140+00:00",
      "updatedAt": "2026-09-10T12:52:48.140+00:00"
    }
  ]
}

Listar Localidades (Lista Simples) ​

Retorna as localidades em formato simplificado (value/label), ideal para selects no cadastro de vagas.

http
GET /v1/ats/user/locations/list

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
searchstringNãoBusca por termo no nome (máx. 150 caracteres).
limitnumberNãoLimite de itens retornados (entre 1 e 500).

Exemplo de Requisição ​

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

json
[
  {
    "value": 1,
    "label": "Av. Dr. Luís Rocha Miranda"
  },
  {
    "value": 2,
    "label": "R. Freire Farto, 70 - Jabaquara"
  }
]

Criar Localidade ​

Cadastra uma nova localidade reutilizável na instância.

http
POST /v1/ats/user/locations

Payload (Body) ​

AtributoTipoObrigatórioDescrição
namestringSimNome ou endereço da localidade (máx. 200 caracteres).
citystringNãoCidade (máx. 200 caracteres).
statestringNãoEstado (máx. 200 caracteres).
countrystringNãoPaís por extenso (máx. 200 caracteres).
countryCodestringNãoCódigo ISO do país com 2 letras (ex.: BR).
latitudenumberNãoLatitude (entre -90 e 90).
longitudenumberNãoLongitude (entre -180 e 180).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/locations" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "R. Freire Farto, 70 - Jabaquara",
    "city": "São Paulo",
    "state": "São Paulo",
    "country": "Brazil",
    "countryCode": "BR",
    "latitude": -23.636660,
    "longitude": -46.645439
  }'

Respostas ​

201 Created

Retorna o ID da localidade criada.

json
{
  "id": 2
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

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

403 Forbidden

Ocorre quando o usuário autenticado não tem permissão de escrita (papel viewer).

json
{
  "code": "FORBIDDEN",
  "message": "Você não tem permissão para gerenciar este recurso"
}

Obter Localidade por ID ​

Recupera os detalhes de uma localidade da instância.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da localidade.

Exemplo de Requisição ​

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

Respostas ​

200 OK

Retorna os dados completos da localidade.

json
{
  "id": 2,
  "atsId": 1,
  "name": "R. Freire Farto, 70 - Jabaquara",
  "city": "São Paulo",
  "state": "São Paulo",
  "country": "Brazil",
  "countryCode": "BR",
  "latitude": "-23.6366600",
  "longitude": "-46.6454390",
  "createdAt": "2026-09-10T12:53:21.543+00:00",
  "updatedAt": "2026-09-10T12:53:21.543+00:00"
}

404 Not Found

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

Atualizar Localidade ​

Atualiza os dados de uma localidade existente.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da localidade.

Payload (Body) ​

Aceita os mesmos campos da criação: name (obrigatório), city, state, country, countryCode, latitude e longitude.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/locations/2" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "R. Freire Farto, 70 - Jabaquara",
    "city": "São Paulo",
    "state": "São Paulo",
    "country": "Brazil",
    "countryCode": "BR",
    "latitude": -23.636660,
    "longitude": -46.645439
  }'

Respostas ​

204 No Content

Atualização concluída com sucesso.

404 Not Found

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

Remover Localidade ​

Exclui uma localidade da instância.

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

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID da localidade.

Exemplo de Requisição ​

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

Geografia ​

Endpoints somente de consulta que retornam países, estados e cidades em formato value/label, pensados para alimentar selects encadeados em formulários de endereço: primeiro o país, depois o estado filtrado pelo país e, por fim, a cidade filtrada pelo estado.

Listar Países ​

Retorna todos os países disponíveis, com busca opcional por nome.

http
GET /v1/ats/user/countries/list

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
searchstringNãoBusca por termo no nome do país (máx. 150 caracteres).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/countries/list?search=Bra" \
  -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 países em formato value/label.

json
[
  {
    "value": 1,
    "label": "Afghanistan"
  },
  {
    "value": 2,
    "label": "Aland Islands"
  }
]

Listar Estados ​

Retorna os estados de um país. Sem o filtro countryId, a lista retorna vazia.

http
GET /v1/ats/user/states/list

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
searchstringNãoBusca por termo no nome do estado (máx. 100 caracteres).
countryIdnumberNãoFiltra os estados pelo ID do país (deve ser positivo).

Exemplo de Requisição ​

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

json
[
  {
    "value": 373,
    "label": "Antwerp"
  },
  {
    "value": 374,
    "label": "Brussels-Capital"
  }
]

422 Unprocessable Entity

Ocorre quando countryId não é um número positivo.

Listar Cidades ​

Retorna as cidades filtradas por estado ou país. Sem stateId ou countryId, a lista retorna vazia.

http
GET /v1/ats/user/cities/list

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
searchstringNãoBusca por termo no nome da cidade (máx. 100 caracteres).
countryIdnumberNãoFiltra as cidades pelo ID do país (deve ser positivo).
stateIdnumberNãoFiltra as cidades pelo ID do estado (deve ser positivo).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/cities/list?stateId=373&search=Camp" \
  -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 cidades em formato value/label.

json
[
  {
    "value": 9753,
    "label": "Abomey"
  },
  {
    "value": 9727,
    "label": "Abomey-Calavi"
  }
]

422 Unprocessable Entity

Ocorre quando stateId ou countryId não é um número positivo.