# Create a role

Creates a role, assigning a user to an account group or business entity.
The `entity_type` parameter determines whether `entity_id` refers to an account group or a business, and constrains which `role_type` values are valid.
See the User roles guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_onboarding_roles) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_onboarding_roles)) for role types and assignment rules.

Endpoint: POST /roles
Version: 1.159.0
Security: oauth-client-credentials

## Security:

  - `oauth-client-credentials` (unknown)
    oauth2 scopes: roles:admin

## Header parameters:

  - `idempotency-key` (string, required)
    A UUID to be used as an idempotency key.  This prevents a duplicate request from being replayed.
https://docs.upvest.co/documentation/concepts/api_concepts/idempotency

  - `upvest-client-id` (string, required)
    Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).

  - `Authorization` (string, required)
    Bearer (access) token from the OAuth flow with correct scopes.
https://datatracker.ietf.org/doc/html/rfc6750

  - `signature` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header

  - `signature-input` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he

  - `upvest-api-version` (string)
    Upvest API version (Note: Do not include quotation marks)

## Request fields (application/json):

  - `user_id` (string, required)
    Unique identifier of the user, as a UUID.

  - `entity_type` (string, required)
    The entity type; must be `ACCOUNT_GROUP` for account group roles.

  - `entity_id` (string, required)
    Universally Unique Identifier (UUID) of the account group.

  - `role_type` (string, required)
    Role type to assign.
* `GUARDIAN` — The user is a legal custodian of the child account group.
* `OWNER` — The second owner of a `JOINT` account group; the first owner is the user the account group was created with. `custody_type` does not apply.
    Enum: "GUARDIAN", "OWNER"

  - `custody_type` (string)
    Custody type for child account groups.
* `SOLE_CUSTODY` — A single guardian has custody of the child account group.
* `JOINT_CUSTODY` — Multiple guardians are required for the child account group.
    Enum: "SOLE_CUSTODY", "JOINT_CUSTODY"

  - `entity_type` (string, required)
    The entity type; must be `BUSINESS` for business roles.

  - `entity_id` (string, required)
    Unique identifier for the business.

  - `role_type` (string, required)
    Role type for a business entity.
* `LEGAL_REPRESENTATIVE` — The user is a legal representative of the business.
* `AUTHORISED_SIGNATORY` — The user is authorised to sign documents and make commitments on behalf of the business.
* `ULTIMATE_BENEFICIAL_OWNER` — The user ultimately owns or controls the business.
* `CONTRACTING_EXECUTIVE` — The user is able to enter into contracts on behalf of the business.
* `TRADER` — The user is authorised to place orders on behalf of the business.
* `SOLE_TRADER` — The user places orders on behalf of a sole trader entity.
    Enum: "LEGAL_REPRESENTATIVE", "AUTHORISED_SIGNATORY", "ULTIMATE_BENEFICIAL_OWNER", "CONTRACTING_EXECUTIVE", "TRADER", "SOLE_TRADER"

## Request examples:

  - `Account Group role` (unknown)

  - `Joint account group owner` (unknown)

  - `Business role` (unknown)

## Response 200:

  - `200` (unknown)
    Role created.

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier for the role.

  - `created_at` (string, required)
    Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `updated_at` (string, required)
    Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `user_id` (string, required)
    Unique identifier of the user, as a UUID.

  - `entity_type` (string, required)
    The entity type; must be `ACCOUNT_GROUP` for account group roles.

  - `entity_id` (string, required)
    Unique identifier of the entity a role is attached to.

  - `role_type` (string, required)
    Role type for account group.
    Enum: "GUARDIAN", "OWNER"

  - `custody_type` (string)
    Custody type for child account groups.
* `SOLE_CUSTODY` — A single guardian has custody of the child account group.
* `JOINT_CUSTODY` — Multiple guardians are required for the child account group.
    Enum: "SOLE_CUSTODY", "JOINT_CUSTODY"

  - `status` (string, required)
    Status of the role assignment.
* `PENDING` — The role has been created but is not yet active.
* `ACTIVE` — The role is active.
* `DEACTIVATED` — The role has been deactivated and cannot be reactivated.
    Enum: "PENDING", "ACTIVE", "DEACTIVATED"

  - `entity_type` (string, required)
    The entity type; must be `BUSINESS` for business roles.

  - `role_type` (string, required)
    Role type for a business entity.
* `LEGAL_REPRESENTATIVE` — The user is a legal representative of the business.
* `AUTHORISED_SIGNATORY` — The user is authorised to sign documents and make commitments on behalf of the business.
* `ULTIMATE_BENEFICIAL_OWNER` — The user ultimately owns or controls the business.
* `CONTRACTING_EXECUTIVE` — The user is able to enter into contracts on behalf of the business.
* `TRADER` — The user is authorised to place orders on behalf of the business.
* `SOLE_TRADER` — The user places orders on behalf of a sole trader entity.
    Enum: "LEGAL_REPRESENTATIVE", "AUTHORISED_SIGNATORY", "ULTIMATE_BENEFICIAL_OWNER", "CONTRACTING_EXECUTIVE", "TRADER", "SOLE_TRADER"

## Response 200 headers (application/json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 400:

  - `400` (unknown)
    Bad Request. The incoming request had a malformed parameter/object.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 400 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 401:

  - `401` (unknown)
    Unauthorized. The caller has not been authenticated.

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 401 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 403:

  - `403` (unknown)
    Forbidden. The caller has been authenticated but is not allowed to take the requested action.

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 403 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 406:

  - `406` (unknown)
    Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value.

## Response 406 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 406 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 429:

  - `429` (unknown)
    Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 429 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 500:

  - `500` (unknown)
    Internal Server Error. The service encountered an unexpected error.

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 500 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 503:

  - `503` (unknown)
    Service Unavailable. The service handling for this request cannot be reached at this time.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 503 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 504:

  - `504` (unknown)
    Gateway Timeout. The service gateway has reached its internal timeout.

## Response 504 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 504 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 200 examples:

  - `Account Group role` (unknown)

  - `Joint account group owner` (unknown)

  - `Business role` (unknown)