# List user roles for company

This endpoint provides list of available user roles for a company.

Endpoint: POST /v3/companies/{companyId}/roles
Version: v3
Security: Bearer

## Path parameters:

  - `companyId` (string, required)
    Identifier of the company.
    Example: "1234a66b-7493-4f41-908c-58ba81093947"

## Request fields (application/json):

  - `searchText` (string)
    Query text to search roles. The match would be case-insensitive.
    Example: "Admin"

  - `pagination` (object, required)
    Pagination information for request.

  - `pagination.offset` (integer)
    The starting index in the list from which results are returned. The value must be greater than or equal to 0.

  - `pagination.limit` (integer)
    Maximum number of results to be fetched.

  - `sortParams` (object)
    Sorting related parameters.

  - `sortParams.sortBy` (string, required)
    The field name to sort roles.
    Enum: "NAME"

  - `sortParams.sortOrder` (string, required)
    Sorting order.
    Enum: "DESC", "ASC"

  - `filters` (array)
    List of filters. Roles matching with any filter would be returned.

  - `filters.roleIds` (array)
    List of role ids.

  - `filters.roleProvidedBy` (array)
    Filter by role providers.
    Enum: "PLATFORM", "COMPANY"

## Response 200 fields (application/json):

  - `roles` (array, required)
    Roles matching with the request.

  - `roles.id` (string, required)
    Role identifier.

  - `roles.name` (string, required)
    Name of the role.
    Example: "User Admin"

  - `roles.description` (string, required)
    A short description of the role mentioning what can it do.
    Example: "Manage users for the company."

  - `roles.isPlatformRole` (boolean, required)
    Whether role is platform provided.

  - `roles.companyId` (string)
    Company ID which owns the role.
    Example: "1aeef911-44cf-49bb-83c7-e06b0d4e7ac2"

  - `roles.permissions` (array, required)
    Permissions granted to the role.

  - `roles.permissions.permission` (string, required)
    Permission
    Enum: "PLATFORM_MANAGEMENT", "TMC_MANAGEMENT", "COMPANY_MANAGEMENT", "USER_MANAGEMENT", "USER_PROFILE", "EVENT_MANAGEMENT", "REPORT_MANAGEMENT", "ACCESS_MANAGEMENT", "TRIP_MANAGEMENT", "AGENT", "DEVELOPER_PLATFORM_MANAGEMENT", "THIRD_PARTY_NOTIFICATION_MANAGEMENT"

  - `roles.permissions.actions` (array, required)
    Actions allowed on the permission like read/write/delete.
    Enum: "ALL", "CREATE", "READ", "WRITE", "DELETE", "PURGE"

  - `roles.createdAt` (object, required)
    Date and time when the role was created.

  - `roles.createdAt.iso8601` (string, required)
    Example: "2017-07-21T17:32Z"

  - `roles.updatedAt` (object, required)
    Date and time when the role was last updated.

  - `roles.createdBy` (object, required)
    User who created the role.

  - `roles.createdBy.id` (string, required)
    Example: "b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3"

  - `roles.createdBy.name` (string)
    Example: "Name"

  - `roles.updatedBy` (object, required)
    User who last updated the role.

  - `pagination` (object, required)
    Pagination information for response.

  - `pagination.totalNumResults` (integer, required)
    Total number of results.

## Response 400 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.

## Response 401 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.

## Response 403 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.