Listar colaboradores

Este endpoint permite listar os colaboradores da empresa de forma paginada, com filtros opcionais por e-mail e CPF.

Regras de negócio e validações

Campos obrigatórios

Nenhum campo é obrigatório. Sem filtros, todos os colaboradores da empresa são retornados.

Campos opcionais

email: Filtro para buscar colaboradores da empresa por e-mail. Pode ser inserido parte do e-mail para realizar a busca. Mínimo de 3 caracteres, máximo de 255.
taxpayerRegistry: Filtro para buscar colaboradores da empresa por CPF. Pode ser inserido parte do CPF para realizar a busca. Mínimo de 3 caracteres, máximo de 20.
maxPageSize: Quantidade máxima de registros que podem ser retornados por página. Valor máximo: 100. Padrão: 100.
pageToken: Token utilizado para acessar a próxima página de colaboradores. Obtido no campo nextPageToken da resposta anterior.
fields: Seletor de campos para filtrar os dados retornados na resposta.

Seletor de campos (`fields`)

O parâmetro fields permite filtrar quais dados serão incluídos na resposta. Os campos disponíveis são organizados em três grupos:

Account

id, firstName, lastName, email, taxpayerRegistry, mobileNumber, createdAt

Para incluir todos os campos de account, use: *account

Attributes

admissionDate, birthDate, biologicalSex, education, language, linkedinUrl, streetAddress, cityAddress, stateAddress, zipCodeAddress, neighborhoodAddress, terminationDate, terminationReason, photo

Para incluir todos os atributos, use: *attributes
Para campos específicos, use o prefixo: attributes.birthDate, attributes.education

Solutions

recruitmentAndSelection, admission, training, engagement, performance, admin

Para incluir todas as soluções, use: *solutions
Para campos específicos, use o prefixo: solutions.training, solutions.admin

Paginação

A listagem é paginada. A resposta inclui o campo nextPageToken quando existem mais registros além da página atual. Utilize esse token no parâmetro pageToken da próxima requisição para acessar os registros subsequentes.

Exemplo de requisição (cURL)

curl 'https://api.gupy.io/user-management/v1/employees?email=john&maxPageSize=50' \
  --header 'Authorization: Bearer bearer_token_value_here'

Possíveis erros

Este endpoint não possui erros de negócio específicos além dos erros de autenticação e autorização abaixo.

Não autenticado

Erro lançado quando o token de autenticação não é informado ou é inválido.

{
  "statusCode": 401,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/employees",
  "method": "GET",
  "title": "UnauthorizedException",
  "message": "Unauthorized"
}

Sem permissão

Erro lançado quando o token de autenticação não possui a permissão necessária (READ ou WRITE) para acessar o endpoint.

{
  "statusCode": 403,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/employees",
  "method": "GET",
  "title": "ForbiddenException",
  "message": "Forbidden"
}