---
title: "Returns one custom role."
method: GET
path: "/api/v1/roles/{id}"
tags: ["Roles"]
---

# Returns one custom role.

`GET /api/v1/roles/{id}`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/roles/{id}`
- Auth: HTTP bearer

Requires `ManageUsers`. Built-in roles have no id; read them from the list. Example: `GET /api/v1/roles/4`.

## Path parameters

- `id` integer, required

## Response `200`

The role.

- RoleDto: A role accounts can hold, as returned by `/api/v1/roles`: the built-in `OrganizationAdmin`, `Manager` and `User` (never `SystemAdmin`), then the organization's custom roles.
  - `id` integer, nullable: Custom role id (use it as `customRoleId` / in `customRoleIds` on the user endpoints); null for a built-in role. Example: `4`.
  - `name` string: Role name; for a built-in role this is the value to send as `role`. Example: `"Manager"`.
  - `description` string: What the role is for. Example: `"Manager with inventory and location management access"`.
  - `isBuiltIn` boolean: True for OrganizationAdmin / Manager / User, which cannot be edited.
  - `rank` integer: Hierarchy rank: OrganizationAdmin 3, Manager 2, User 1; custom roles 0 (they add permissions, not rank).
  - `permissions` string[]: Permissions the role grants, as FlexPermissions names. Example: `["ViewInventory", "ManageJobs"]`.
  - `createdAt` string, date-time, nullable: UTC creation time (ISO-8601); null for built-in roles.
  - `updatedAt` string, date-time, nullable: UTC last modification time (ISO-8601); null for built-in roles.

## Other responses

- `304`: Unchanged since the supplied ETag.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: No such custom role in this organization.
- `429`: Too Many Requests

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)