{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Role-based activation","description":"Welcome to the Upvest API documentation. Here you will find all the information you need to integrate with our API.","siteUrl":"https://docs.upvest.co","image":"/assets/upvest-logo-card.ee25ccc59849324b0b73151a5c972c87639419556344db0b6dcf518151cb4c3c.925ff8b2.png","keywords":"documentation, api","lang":"en-US","meta":[{"name":"description","content":"Welcome to the Upvest API documentation. Here you will find all the information you need to integrate with our API."},{"name":"image","content":"/assets/upvest-logo-card.ee25ccc59849324b0b73151a5c972c87639419556344db0b6dcf518151cb4c3c.925ff8b2.png"},{"name":"twitter:card","content":"summary_large_image"},{"name":"twitter:title","content":"Welcome to the Upvest API Documentation"},{"name":"twitter:image","content":"/assets/upvest-logo-card.ee25ccc59849324b0b73151a5c972c87639419556344db0b6dcf518151cb4c3c.925ff8b2.png"},{"name":"twitter:description","content":"Welcome to the Upvest API documentation. Here you will find all the information you need to integrate with our API."},{"name":"og:url","content":"https://docs.upvest.co/"},{"name":"og:title","content":"Welcome to the Upvest API Documentation"},{"name":"og:description","content":"Welcome to the Upvest API documentation. Here you will find all the information you need to integrate with our API."},{"name":"og:image","content":"/assets/upvest-logo-card.ee25ccc59849324b0b73151a5c972c87639419556344db0b6dcf518151cb4c3c.925ff8b2.png"}]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"role-based-activation","__idx":0},"children":["Role-based activation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section explains the relationship between users and user roles. It also shows the requirements each account group type must meet before it can be funded and accept orders."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"users-roles-and-entities","__idx":1},"children":["Users, roles, and entities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/roles"]}," endpoint shows an end user's connection to a specific entity as listed in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity_type"]}," field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For personal, child, and joint accounts, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity_type"]}," field equals ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_GROUP"]},". For business accounts, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity_type"]}," field equals ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BUSINESS"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two distinct sets of conditions govern activation:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Role activation"]},": A role is created in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]}," and transitions to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]}," once the role's requirements, such as regulatory checks, are met. The required checks depend on the type of role."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account group activation"]},": An account group transitions from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING_APPROVAL"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]}," once all of its ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required roles are active"]}," and any entity-level checks have passed."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These statuses are otherwise independent. An end user can hold a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]}," role, and an account group remains in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING_APPROVAL"]}," until its required roles are active. An end user's role reaching the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]}," status means their own onboarding is complete, but they must still be mapped to a role to access an account group."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"assigning-roles","__idx":2},"children":["Assigning roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table highlights whether you must directly assign the end user's role or if the role is automatically assigned."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For child accounts, you must assign the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GUARDIAN"]}," roles for the account. For joint accounts, you must assign a second ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}," role. For business accounts, you must assign roles to all of the required users."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition, roles like the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHILD"]}," roles are automatically assigned."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Role"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Role"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Entity type"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Entity type"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Assignment"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Assignment"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_GROUP"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Assigned by Upvest when a personal account group is created, and when a child account group converts to a personal account group."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHILD"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_GROUP"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Assigned by Upvest when a child account group is created."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JOINT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_GROUP"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["First user automatically assigned an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}," role by Upvest. You must assign the second end user an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}," role via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /roles"]}," endpoint."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GUARDIAN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_GROUP"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Created by you with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /roles"]}," endpoint."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LEGAL_REPRESENTATIVE"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORISED_SIGNATORY"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ULTIMATE_BENEFICIAL_OWNER"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONTRACTING_EXECUTIVE"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRADER"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOLE_TRADER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BUSINESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Created by client via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /roles"]}," endpoint."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For account groups, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GUARDIAN"]}," (for child accounts) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}," (for joint accounts) are the only two values accepted as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role_type"]}," in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /roles"]}," request."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/users/users_onboarding_roles"},"children":["Creating user roles"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"assigning-multiple-roles","__idx":3},"children":["Assigning multiple roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once configured, an end user's identity verification, compliance screening, and tax residency data can be referenced by every role that user takes on. After onboarding, you can assign as many roles as the end user needs:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, the same end user can be the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}," of their own personal account group, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GUARDIAN"]}," on a child account group, and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ULTIMATE_BENEFICIAL_OWNER"]}," of a business."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Assign a separate role for each capacity, using one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /roles"]}," request per role. Do not create duplicate users."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Regulatory checks are not repeated for subsequent roles for an end user."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For businesses, every assigned user is screened, not only those covering the minimum required roles. A business can carry additional ultimate beneficial owners, several legal representatives, or extra traders, and all of them are screened."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"activation-requirements-per-account-group-type","__idx":4},"children":["Activation requirements per account group type"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An account group accepts neither funds nor orders until its required roles are active and any entity-level checks have passed."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Account group type"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account group type"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Roles required for activation"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Roles required for activation"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PERSONAL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Only one active ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHILD"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Active ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GUARDIAN"]}," roles — one for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOLE_CUSTODY"]},", two for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JOINT_CUSTODY"]},", plus one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHILD"]}," role"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JOINT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Two active ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}," roles"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FRENCH_PEA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ISA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENSION_DE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Only one active ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BUSINESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Corporate entities: must have an active ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ULTIMATE_BENEFICIAL_OWNER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LEGAL_REPRESENTATIVE"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONTRACTING_EXECUTIVE"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Sole traders: one active ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOLE_TRADER"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required roles for business accounts depend on the legal structure."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the requirements that apply to a specific legal type, refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/accounts/businesses_implementing_corporate"},"children":["Creating a corporate business account"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/accounts/businesses_implementing_sole_trader"},"children":["Creating a sole trader business account"]}," sections in the guide."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tax-wrapped-account-groups","__idx":5},"children":["Tax-wrapped account groups"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tax wrappers carry their own activation requirements, and the account group and its accounts are activated automatically once the wrapper reaches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more details refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/tax_wrappers/tax_wrappers_overview"},"children":["Tax wrappers guide"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"regulatory-checks-by-operating-model","__idx":6},"children":["Regulatory checks by operating model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Which regulatory checks gate role activation depends on your operating model, and is configured as part of your setup with Upvest:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"take-our-license---single-accounts","__idx":7},"children":["Take our license - Single Accounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identity verification, compliance screening, and the relevant terms and conditions are required before a role activates."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An account group starts in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING_APPROVAL"]}," and transitions to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]}," once those checks clear, typically within seconds."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bring-your-own-license---single-accounts","__idx":8},"children":["Bring your own license - Single Accounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Typically only a user identifier (for transaction reporting) and tax residency (for tax handling) are required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because the role requirements are minimal, roles and the account group usually activate immediately on creation, and you may observe the account group moving directly to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/users/users_onboarding_checks"},"children":["Conducting regulatory checks"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tracking-activation","__idx":9},"children":["Tracking activation"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tracking-role-activation","__idx":10},"children":["Tracking role activation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Activation is asynchronous and condition-driven. You can subscribe to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/users/users_webhooks#role-events"},"children":["role webhook events"]}," to automatically receive notifications of a role’s activation status. Listen for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ROLE.CREATED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ROLE.ACTIVATED"]}," webhook events."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tracking-account-group-and-account-activation","__idx":11},"children":["Tracking account group and account activation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To detect readiness, listen for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_GROUP.ACTIVATED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT.ACTIVATED"]}," as well."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/users/users_webhooks"},"children":["User webhooks"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/accounts/accounts_webhooks"},"children":["Account and account group webhooks"]}," sections of the guides."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"role-lifecycle","__idx":12},"children":["Role lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Account group roles and business roles behave differently over time."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"personal-joint-and-child-accounts","__idx":13},"children":["Personal, joint, and child accounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Account group roles, like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GUARDIAN"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHILD"]},", persist until the account group is closed. They define who the account group exists for, so you cannot deactivate them via the API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /roles/{role_id}"]}," request rejects the attempt with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 Forbidden"]}," error message."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For child accounts, roles are automatically updated when the child reaches the age at which they can manage the account themselves. When this occurs, the child account group converts to a personal account group and the following roles are updated:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GUARDIAN"]}," roles are deactivated."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The former ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHILD"]}," role holder is assigned the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OWNER"]}," role."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition, the account group retains its full transaction history."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ROLE.DEACTIVATED"]}," event for each guardian and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ROLE.CREATED"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ROLE.ACTIVATED"]}," event for the new owner."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"business-accounts","__idx":14},"children":["Business accounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Business roles can change over the lifetime of the entity, because they record who acts for the business in a given capacity rather than who the business exists for. You can deactivate a business role with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /roles/{role_id}"]}," endpoint:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only roles whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity_type"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BUSINESS"]}," can be deactivated through this endpoint."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deactivation is terminal. A deactivated role cannot be reactivated. To restore the capacity, create a new role for the same user and entity."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The role remains queryable with status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEACTIVATED"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The call is idempotent. Calling it on an already-deactivated role returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," with no side effects."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ROLE.DEACTIVATED"]}," event is emitted on the first successful deactivation only."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deactivating a role does not exempt the business from its minimum role requirements. For example, if you deactivate the only active ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LEGAL_REPRESENTATIVE"]}," on a corporate business, assign a replacement so the entity continues to meet the requirements described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#activation-requirements-per-account-group-type"},"children":["Activation requirements per account group type"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, refer to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/tol/guides/users/users_onboarding_roles"},"children":["Creating user roles"]},"."]}]},"headings":[{"value":"Role-based activation","id":"role-based-activation","depth":1},{"value":"Users, roles, and entities","id":"users-roles-and-entities","depth":2},{"value":"Assigning roles","id":"assigning-roles","depth":2},{"value":"Assigning multiple roles","id":"assigning-multiple-roles","depth":2},{"value":"Activation requirements per account group type","id":"activation-requirements-per-account-group-type","depth":2},{"value":"Tax-wrapped account groups","id":"tax-wrapped-account-groups","depth":3},{"value":"Regulatory checks by operating model","id":"regulatory-checks-by-operating-model","depth":2},{"value":"Take our license - Single Accounts","id":"take-our-license---single-accounts","depth":3},{"value":"Bring your own license - Single Accounts","id":"bring-your-own-license---single-accounts","depth":3},{"value":"Tracking activation","id":"tracking-activation","depth":2},{"value":"Tracking role activation","id":"tracking-role-activation","depth":3},{"value":"Tracking account group and account activation","id":"tracking-account-group-and-account-activation","depth":3},{"value":"Role lifecycle","id":"role-lifecycle","depth":2},{"value":"Personal, joint, and child accounts","id":"personal-joint-and-child-accounts","depth":3},{"value":"Business accounts","id":"business-accounts","depth":3}],"frontmatter":{"seo":{"title":"Role-based activation"}},"lastModified":"2026-10-02T11:02:10.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/tol/guides/users/role_based_activation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}