# Create a role

Creates a role in the account you are calling as. The account is taken from the
caller and cannot be set from the request. The response is the same shape as
reading the role, so a follow-up read is not needed.
`name`, `code` and `permissions` are all required; a request missing any of them
comes back as a `422` naming the ones at fault. A `permissions` object granting
more than the caller's own role holds is rejected the same way.
**`options` is stored whole.** The object you send replaces the stored one rather
than merging into it, so send every key you want to keep.

Endpoint: POST /api/v2/account/role
Version: 2.0.0
Security: default

## Header parameters:

  - `Rosterfy-Platform` (string)

## Request fields (application/json):

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

  - `permissions` (object, required)
    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.

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

  - `code` (string, required)
    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.

  - `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 201 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)