# Role events

Notifies subscribers of role lifecycle events.
Triggered when a role is created, activated, or deactivated.
When an account group is created for a user, Upvest creates a role for that user automatically: `CHILD` for a child account group, `OWNER` for all other types. `ROLE.ACTIVATED` signals that the user has met the onboarding requirements for the account group or business.
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.

Endpoint: POST Role events
Version: 1.156.0

## Request fields (application/json):

  - `id` (string, required)
    Event unique identifier

  - `created_at` (string, required)
    Date and time when the event 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)

  - `type` (string, required)
    Event type.
* `ROLE.CREATED` — A role has been created.
* `ROLE.ACTIVATED` — A role has become active.
* `ROLE.DEACTIVATED` — A role has been deactivated.
    Enum: "ROLE.CREATED", "ROLE.ACTIVATED", "ROLE.DEACTIVATED"

  - `object` (any, required)
    The role the event relates to — either an account group role or a business role.

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

  - `object.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)

  - `object.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)

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

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

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

  - `object.role_type` (string, required)
    Role type for an account group.
* `OWNER` — The user owns the account group.
* `GUARDIAN` — The user is a legal custodian of a child account group.
* `CHILD` — The user is the child beneficiary of a child account group.
    Enum: "OWNER", "GUARDIAN", "CHILD"

  - `object.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"

  - `object.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"

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

  - `object.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"

  - `webhook_id` (string, required)
    Webhook unique identifier.

## Request examples:

  - `Account Group role event` (unknown)

  - `Business role event` (unknown)

## Response 200:

  - `200` (unknown)
    Request has been processed successfully.