# Update a role

Updates a role and returns it in the same shape as reading it. Every field is
optional; a request with an empty body succeeds and changes nothing.
**You cannot update a role you hold yourself.** Doing so is refused with a `403`
and a message saying so, which is deliberate rather than an authorisation
accident - it stops an administrator editing their own permissions. Have someone
on a different role make the change.
A `permissions` object granting more than the caller's own role holds is rejected
with a `422`.
**`options` is stored whole.** The object you send replaces the stored one rather
than merging into it, so an update carrying only `options.protect_pii` clears
every other key under it. Send every key you want to keep.

Endpoint: PUT /api/v2/account/role/{id}
Version: 2.0.0
Security: default

## Path parameters:

  - `id` (integer, required)
    The ID of the role.

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

  - `name` (string)
    Display name of the role, up to 255 characters. This is what administrators pick from when assigning someone a role.

  - `permissions` (object)
    What the role may do, as an object of permission names against true or false. The set of names is the account's own and is not enumerated here - read an existing role to see the ones available to you, and send the same shape back. A role cannot be given a permission the caller's own role does not hold; attempting it is rejected.

  - `horizontal` (object)
    Optional limits on which records the role may act on, as an object keyed by the area being limited. Structure is not part of the contract - build the limits in the admin console and send back what a read returns. Entries naming an area the role has no permission for are dropped rather than rejected, so a role can come back with fewer limits than were sent.

  - `prefill` (array)
    Optional values to fill in automatically on records this role creates. Structure is not part of the contract - build it in the admin console and send back what a read returns. Each attribute may appear only once.

  - `is_lite_admin` (boolean)
    Whether the role is a lite administrator, a reduced role whose permissions are limited to a fixed subset. Setting it discards any permission outside that subset rather than rejecting the request.

  - `code` (string)
    Stable identifier for the role, up to 64 characters of letters, digits, hyphens and underscores; anything else is stripped. Use it to map the role to one in your identity provider when signing in through SSO. Must be unique within the account, and one is generated if you leave it empty.

  - `is_simple_attribute_selection` (boolean)
    Whether the admin console offers this role the simplified attribute picker instead of the full one.

  - `is_restricted` (boolean)
    Whether the role is limited to specific records within the areas named in access_required_modules, chosen per person rather than per role. Update only.

  - `is_inheritable` (boolean)
    Whether accounts below this one may use the role as well as the account that owns it.

  - `access_required_modules` (array)
    Which areas the per-person limits apply to, as a list of area names: headcount_functional_area, headcount_functional_area_job_title, headcount_location, headcount_location_venue or headcount_user_type. Cleared unless is_restricted is set. Update only.

  - `options` (object)

  - `options.protect_pii` (boolean)
    Whether people with this role are blocked from seeing private fields on a record. Requires the account to have role-based field protection enabled.

  - `options.protect_pii_all` (boolean)
    Whether the block covers every private field rather than a chosen list. Only applies when options.protect_pii is set.

  - `options.protect_pii_by_field` (array)
    Which fields to block, as a list of attribute codes. Used only when options.protect_pii is set and options.protect_pii_all is not.

  - `options.mask_pii` (boolean)
    Whether private fields are shown to this role with their values obscured rather than hidden outright. Requires the account to have role-based field masking enabled.

  - `options.mask_pii_all` (boolean)
    Whether masking covers every private field rather than a chosen list. Only applies when options.mask_pii is set.

  - `options.mask_pii_by_field` (array)
    Which fields to mask, as a list of attribute codes. Used only when options.mask_pii is set and options.mask_pii_all is not.

## Response 200 fields (application/json):

  - `object` (object)

  - `object.id` (integer)

  - `object.name` (string)

  - `object.code` (string)

  - `object.permissions` (object)

  - `object.permissions.account` (boolean)

  - `object.permissions.account:read` (boolean)

  - `object.permissions.account:update` (boolean)

  - `object.permissions.event` (boolean)

  - `object.permissions.event:read` (boolean)

  - `object.permissions.event:create` (boolean)

  - `object.permissions.event:update` (boolean)

  - `object.permissions.user` (boolean)

  - `object.permissions.user:read` (boolean)

  - `object.permissions.user:update` (boolean)

  - `object.permissions.report` (boolean)

  - `object.permissions.report:read` (boolean)

  - `object.horizontal` (string | null)

  - `object.prefill` (string | null)

  - `object.is_system` (integer)

  - `object.is_lite_admin` (integer)

  - `object.is_simple_attribute_selection` (integer)

  - `object.is_restricted` (integer)

  - `object.is_inheritable` (integer)

  - `object.access_required_modules` (string | null)

  - `object.options` (string | null)

  - `object.created_at` (string)

  - `object.updated_at` (string)

  - `object.user_dashboard_id` (string | null)

  - `nice` (object)

  - `nice.rrn` (string)

  - `relations` (array)

  - `permissions` (object)

  - `permissions.read` (boolean)

  - `permissions.update` (boolean)

  - `permissions.delete` (boolean)

  - `permissions.update_message` (string)

  - `permissions.copy` (boolean)

## Response 403 fields (application/json):

  - `message` (string)