Empresas & Membros

Uma instância de ATS pode abrigar várias empresas — útil para grupos econômicos, consultorias de recrutamento ou operações com unidades de negócio distintas. Cada empresa tem seu próprio nome, slug, site e identidade visual (logo), e uma delas pode ser marcada como padrão (isDefault) da instância.

O vínculo entre usuários e empresas é feito pelos membros (company-users): cada membro associa um usuário a uma empresa com um papel (role), que define o que ele pode ver e fazer naquela empresa. É esse vínculo que sustenta o controle de acesso (RBAC) de todo o módulo.

Headers obrigatórios

Todas as requisições devem incluir o header X-Ats-Id (UUID) com o identificador da instância de ATS, além de Authorization: Bearer {token} com o token de um usuário staff (guard atsUser). Endpoints de escrita são restritos a usuários com papel owner ou admin.

Estrutura de Dados Principal

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

Campo	Tipo	Descrição
`name`	`String`	Nome da empresa (máx. 160 caracteres).
`slug`	`String`	Slug gerado automaticamente a partir do nome.
`legalName`	`String`	Razão social (máx. 200 caracteres).
`website`	`String`	Site da empresa (máx. 200 caracteres).
`about`	`String`	Descrição/apresentação da empresa.
`atsFileId`	`Number`	ID do arquivo (logo) vinculado à empresa.
`atsFile`	`Object`	Dados do arquivo vinculado (`name`, `url`).
`isDefault`	`Boolean`	Indica se é a empresa padrão da instância.

Papéis (roles)

O papel de um membro define suas permissões dentro da empresa:

Role	Escopo
`owner` / `admin`	Acesso total a todas as empresas da instância, incluindo configurações (empresas, pipelines, usuários, motivos de recusa).
`recruiter` / `hiring_manager`	Gerenciam vagas, candidaturas, departamentos e conteúdo das empresas vinculadas.
`interviewer`	Leitura das empresas vinculadas + criar/gerenciar entrevistas e avaliações.
`viewer`	Somente leitura, nas empresas vinculadas.

Empresas

Endpoints para gerenciamento das empresas da instância. A listagem está disponível para qualquer usuário staff autenticado; a escrita (criar, atualizar e remover) é restrita a owner e admin.

Listar Empresas

Lista todas as empresas da instância, com paginação e busca.

http

GET /v1/ats/user/companies

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

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/companies?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 empresas.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 2,
      "atsId": 1,
      "name": "TechNova Soluções",
      "slug": "technova-solucoes",
      "legalName": "TechNova Soluções em Tecnologia LTDA",
      "website": "https://www.technova.com.br",
      "atsFileId": 1,
      "about": "A TechNova é uma empresa brasileira de tecnologia focada em soluções de recrutamento e seleção, com atuação em todo o território nacional.",
      "isDefault": false,
      "createdAt": "2026-09-11T02:29:21.506+00:00",
      "updatedAt": "2026-09-11T02:29:21.506+00:00",
      "atsFile": {
        "id": 1,
        "name": "curriculo.pdf",
        "url": "https://s3.sa-east-1.amazonaws.com/tavares-dev/files/7af7ff84-4b0e-4ee8-becb-308d88dc7997.pdf"
      }
    },
    {
      "id": 1,
      "atsId": 1,
      "name": "Catho",
      "slug": "catho",
      "legalName": null,
      "website": null,
      "atsFileId": null,
      "about": null,
      "isDefault": true,
      "createdAt": "2026-09-10T02:10:58.777+00:00",
      "updatedAt": "2026-09-10T02:10:58.777+00:00",
      "atsFile": null
    }
  ]
}

Listar Empresas (Lista Simples)

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

http

GET /v1/ats/user/companies/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`search`	`string`	Não	Busca por termo no nome (máx. 150 caracteres).
`limit`	`number`	Não	Limite de itens retornados (entre 1 e 500).

Exemplo de Requisição

bash

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

json

[
  {
    "value": 1,
    "label": "Catho"
  },
  {
    "value": 2,
    "label": "TechNova Soluções"
  }
]

Criar Empresa

Cria uma nova empresa na instância. O slug é gerado automaticamente a partir do nome. Se isDefault for true, a empresa padrão anterior é desmarcada automaticamente.

http

POST /v1/ats/user/companies

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome da empresa (máx. 160 caracteres). O slug gerado deve ser único na instância.
`legalName`	`string`	Não	Razão social (máx. 200 caracteres).
`website`	`string`	Não	Site da empresa (máx. 200 caracteres).
`about`	`string`	Não	Descrição/apresentação da empresa.
`atsFileId`	`number`	Não	ID do arquivo (logo) da empresa (deve existir na instância).
`isDefault`	`boolean`	Não	Marca a empresa como padrão da instância.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/companies" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TechNova Soluções",
    "legalName": "TechNova Soluções em Tecnologia LTDA",
    "website": "https://www.technova.com.br",
    "about": "A TechNova é uma empresa brasileira de tecnologia focada em soluções de recrutamento e seleção, com atuação em todo o território nacional.",
    "atsFileId": 1,
    "isDefault": false
  }'

Respostas

201 Created

Retorna o ID da empresa criada.

json

{
  "id": 2
}

422 Unprocessable Entity

Erro de validação nos campos enviados (por exemplo, nome cujo slug já existe na instância).

json

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

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

Obter Empresa por ID

Recupera os detalhes de uma empresa da instância.

http

GET /v1/ats/user/companies/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID da empresa.

Exemplo de Requisição

bash

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

Respostas

200 OK

Retorna os dados da empresa, incluindo o arquivo vinculado (atsFile).

json

{
  "id": 1,
  "atsId": 1,
  "name": "Catho",
  "slug": "catho",
  "legalName": null,
  "website": null,
  "atsFileId": null,
  "about": null,
  "isDefault": true,
  "createdAt": "2026-09-10T02:10:58.777+00:00",
  "updatedAt": "2026-09-10T02:10:58.777+00:00",
  "atsFile": null
}

404 Not Found

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

Atualizar Empresa

Atualiza os dados de uma empresa existente. O slug é regenerado a partir do novo nome. Se isDefault for true, a empresa padrão anterior é desmarcada automaticamente.

http

PUT /v1/ats/user/companies/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID da empresa.

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome da empresa (máx. 160 caracteres, único na instância).
`legalName`	`string`	Não	Razão social (máx. 200 caracteres).
`website`	`string`	Não	Site da empresa (máx. 200 caracteres).
`about`	`string`	Não	Descrição/apresentação da empresa.
`atsFileId`	`number`	Não	ID do arquivo (logo) da empresa (deve existir na instância).
`isDefault`	`boolean`	Não	Marca a empresa como padrão da instância.

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/companies/1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TechNova Soluções",
    "legalName": "TechNova Soluções em Tecnologia LTDA",
    "website": "https://www.technova.com.br",
    "about": "A TechNova é uma empresa brasileira de tecnologia focada em soluções de recrutamento e seleção, com atuação em todo o território nacional.",
    "atsFileId": 1,
    "isDefault": true
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Erro de validação nos campos enviados.

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

Remover Empresa

Exclui uma empresa da instância (soft delete).

http

DELETE /v1/ats/user/companies/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID da empresa.

Exemplo de Requisição

bash

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

Respostas

204 No Content

Remoção concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

Membros

Endpoints para gerenciar o vínculo entre usuários e empresas. A combinação empresa + usuário é única: um mesmo usuário não pode ser vinculado duas vezes à mesma empresa. Todas as operações de escrita são restritas a owner e admin.

Regra do último owner

Não é permitido remover nem rebaixar (mudar o papel) o único owner de uma empresa. Nessas situações a API responde 422 com o código LAST_OWNER.

Listar Membros

Lista os membros de uma empresa, com paginação e filtro por papel.

http

GET /v1/ats/user/company-users

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`atsCompanyId`	`number`	Sim	ID da empresa (deve existir na instância).
`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).
`role`	`enum`	Não	Filtra por papel: `owner`, `admin`, `recruiter`, `hiring_manager`, `interviewer` ou `viewer`.
`orderBy`	`enum`	Não	Ordena por `id`, `role` ou `createdAt`.
`orderDirection`	`enum`	Não	Direção da ordenação: `asc` ou `desc`.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/company-users?atsCompanyId=1" \
  -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 membros da empresa, com os dados do usuário em atsUser.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "atsId": 1,
      "atsCompanyId": 1,
      "atsUserId": 1,
      "role": "owner",
      "createdAt": "2026-09-10T02:10:58.936+00:00",
      "updatedAt": "2026-09-10T02:10:58.936+00:00",
      "atsUser": {
        "id": 1,
        "firstName": "John",
        "lastName": "Doe (updated)",
        "email": "gerson_tavares@live.com",
        "jobTitle": "Enginner Senior",
        "avatarUrl": null,
        "isActive": true
      }
    }
  ]
}

422 Unprocessable Entity

Ocorre quando atsCompanyId não é informado ou a empresa não existe na instância.

Vincular Membro

Vincula um usuário a uma empresa com um papel. A combinação empresa + usuário deve ser única.

http

POST /v1/ats/user/company-users

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`atsCompanyId`	`number`	Sim	ID da empresa (deve existir na instância). Também aceito como parâmetro de query.
`atsUserId`	`number`	Sim	ID do usuário (deve existir na instância e não estar vinculado à empresa).
`role`	`enum`	Sim	Papel do membro: `owner`, `admin`, `recruiter`, `hiring_manager`, `interviewer` ou `viewer`.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/company-users?atsCompanyId=1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "atsUserId": 2,
    "role": "owner"
  }'

Respostas

201 Created

Retorna o ID do vínculo criado.

json

{
  "id": 2
}

422 Unprocessable Entity

Erro de validação: usuário já vinculado à empresa, usuário ou empresa inexistentes na instância, ou papel inválido.

json

{
  "errors": [
    {
      "message": "The atsUserId has already been taken",
      "rule": "database.unique",
      "field": "atsUserId"
    }
  ]
}

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

Atualizar Papel do Membro

Altera o papel de um membro em uma empresa. Não é permitido rebaixar o único owner da empresa.

http

PUT /v1/ats/user/company-users/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do vínculo (membro).

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`role`	`enum`	Sim	Novo papel: `owner`, `admin`, `recruiter`, `hiring_manager`, `interviewer` ou `viewer`.

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/company-users/2?atsCompanyId=1" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando se tenta rebaixar o único owner da empresa.

json

{
  "message": "Não é possível remover ou rebaixar o único owner da empresa",
  "code": "LAST_OWNER"
}

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

404 Not Found

Ocorre quando o vínculo não existe na instância.

Remover Membro

Remove o vínculo de um usuário com uma empresa. Não é permitido remover o único owner da empresa.

http

DELETE /v1/ats/user/company-users/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do vínculo (membro).

Exemplo de Requisição

bash

curl -X DELETE "https://api.us.basis.tavares.in/v1/ats/user/company-users/2?atsCompanyId=1" \
  -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

Ocorre quando se tenta remover o único owner da empresa.

json

{
  "message": "Não é possível remover ou rebaixar o único owner da empresa",
  "code": "LAST_OWNER"
}

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

404 Not Found

Ocorre quando o vínculo não existe na instância.

Empresas & Membros ​

Estrutura de Dados Principal ​

Papéis (roles) ​

Empresas ​

Listar Empresas ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Listar Empresas (Lista Simples) ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Empresa ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Empresa por ID ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Atualizar Empresa ​

Parâmetros de Rota ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Remover Empresa ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Membros ​

Listar Membros ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Vincular Membro ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Atualizar Papel do Membro ​

Parâmetros de Rota ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Remover Membro ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Empresas & Membros

Estrutura de Dados Principal

Papéis (roles)

Empresas

Listar Empresas

Parâmetros de Query

Exemplo de Requisição

Respostas

Listar Empresas (Lista Simples)

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Empresa

Payload (Body)

Exemplo de Requisição

Respostas

Obter Empresa por ID

Parâmetros de Rota

Exemplo de Requisição

Respostas

Atualizar Empresa

Parâmetros de Rota

Payload (Body)

Exemplo de Requisição

Respostas

Remover Empresa

Parâmetros de Rota

Exemplo de Requisição

Respostas

Membros

Listar Membros

Parâmetros de Query

Exemplo de Requisição

Respostas

Vincular Membro

Payload (Body)

Exemplo de Requisição

Respostas

Atualizar Papel do Membro

Parâmetros de Rota

Payload (Body)

Exemplo de Requisição

Respostas

Remover Membro

Parâmetros de Rota

Exemplo de Requisição

Respostas