--- title: "Create a role" method: POST path: "/roles" tags: ["Roles"] --- # Create a role `POST /roles` 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. ## Headers - `idempotency-key` string, uuid, required ## Request body - union — Request schema for creating a role. - object — Request to create a role assignment for an account group. - `user_id` string, uuid, 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, uuid, required — Universally Unique Identifier (UUID) of the account group. - `role_type` 'GUARDIAN' | 'OWNER', 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. - `custody_type` 'SOLE_CUSTODY' | 'JOINT_CUSTODY' — 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. - object — Request to create a role for a business entity. - `user_id` string, uuid, required — Unique identifier of the user, as a UUID. - `entity_type` string, required — The entity type; must be `BUSINESS` for business roles. - `entity_id` string, uuid, required — Unique identifier for the business. - `role_type` 'LEGAL_REPRESENTATIVE' | 'AUTHORISED_SIGNATORY' | 'ULTIMATE_BENEFICIAL_OWNER' | 'CONTRACTING_EXECUTIVE' | 'TRADER' | 'SOLE_TRADER', 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. ## Response `200` Role created. - union — Response schema for creating a role. - object — Role assignment for an account group. - `id` string, uuid, required — Unique identifier for the role. - `created_at` string, date-time, 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, date-time, 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, uuid, 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, uuid, required — Unique identifier of the entity a role is attached to. - `role_type` 'OWNER' | 'GUARDIAN', required — Role type for account group. - `custody_type` 'SOLE_CUSTODY' | 'JOINT_CUSTODY' — 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. - `status` 'PENDING' | 'ACTIVE' | 'DEACTIVATED', 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. - object — Role assignment for a business entity. - `id` string, uuid, required — Unique identifier for the role. - `created_at` string, date-time, 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, date-time, 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, uuid, required — Unique identifier of the user, as a UUID. - `entity_type` string, required — The entity type; must be `BUSINESS` for business roles. - `entity_id` string, uuid, required — Unique identifier of the entity a role is attached to. - `role_type` 'LEGAL_REPRESENTATIVE' | 'AUTHORISED_SIGNATORY' | 'ULTIMATE_BENEFICIAL_OWNER' | 'CONTRACTING_EXECUTIVE' | 'TRADER' | 'SOLE_TRADER', 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. - `status` 'PENDING' | 'ACTIVE' | 'DEACTIVATED', 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. ## Other responses - `400` — Bad Request. The incoming request had a malformed parameter/object. - `401` — Unauthorized. The caller has not been authenticated. - `403` — Forbidden. The caller has been authenticated but is not allowed to take the requested action. - `406` — Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value. - `429` — Too Many Requests. The caller has exceeded their quota for the time period and has been throttled. - `500` — Internal Server Error. The service encountered an unexpected error. - `503` — Service Unavailable. The service handling for this request cannot be reached at this time. - `504` — Gateway Timeout. The service gateway has reached its internal timeout. ## Changes - **2026-09-16** `85aff1852bf8` — 1 warning, 1 info - added the new `OWNER` enum value to the `oneOf[subschema #1: Account Group Role - Create - Response]/allOf[subschema #2]/role_type` response property for the response status `200` - added the new `OWNER` enum value to the request property `anyOf[subschema #1: Account Group Role - Create - Request]/role_type` [Change history](https://skmtc.dev/upvest/apis/upvest-investment-api/changes/roles/post.md) --- [API](https://skmtc.dev/upvest/apis/upvest-investment-api.md) · [All operations](https://skmtc.dev/upvest/apis/upvest-investment-api/llms.txt) · [OpenAPI document](https://skmtc.dev/upvest/apis/upvest-investment-api/revisions/25a6cd1e39de?raw)