{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab"]},"type":"markdown"},"seo":{"title":"Creating user roles","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"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"creating-user-roles","__idx":0},"children":["Creating user roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both Business accounts and Child accounts require clients to set up users with specific roles. To help facilitate this, Upvest provides the /roles API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prior to adding a user role, you must first create both the user and either a child account group or business entity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition you must work with Upvest to enable the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["roles:admin"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["roles:read"]}," scopes for authentication."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setting-the-users-role","__idx":2},"children":["Setting the user’s role"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can set a user’s role for both child accounts and business account users as follows:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["POST /roles"]},{"$$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":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Field"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Description"]}]}]}]},{"$$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":["user_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The user’s unique identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Sets whether the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity_id"]}," parameter equals the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," of a child account group or business entity. Accepts the following values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_GROUP"]},": Used for child accounts groups.   ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BUSINESS"]},": Used for business entities."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unique identifier for either the child account group or the business entity depending on the value of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity_type"]}," parameter."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Sets the specific role to map to the user.   For child accounts: GUARDIAN: The user is a legal custodian for the child account group. CHILD: The actual child beneficiary for a child account. The owner of the child account group is automatically set to the child. For business accounts: ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LEGAL_REPRESENTATIVE"]},": a designated individual that serves as an official legal representative for the business.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," -  ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHORISED_SIGNATORY"]},": an individual that is given the legal right to sign documents/make commitments on behalf of a business.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," -  ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ULTIMATE_BENEFICIAL_OWNER"]},": individual who ultimately owns or controls the business.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONTRACTING_EXECUTIVE"]},": an individual that is able to enter contracts on behalf of a business.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRADER"]},": an individual that is permitted to trade on behalf of a business.  NOTE: Business accounts must assign at least one (1) Ultimate beneficial owner and at least one (1) Legal representative and one Contracting Executive to the business."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unique identifier of the transfer. Useful for API consumers to build special logic on their side"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Additional parameter for child accounts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custody_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Sets whether a single or multiple guardian roles are required for the child account group.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOLE_CUSTODY"]}," - Single guardian",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JOINT_CUSTODY"]}," - Multiple guardians required"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples-request-and-response-for-child-accounts","__idx":3},"children":["Examples request and response for child accounts"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-account-group-role-request","__idx":4},"children":["Example Account Group role request"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Request","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"user_id\": \"9c36af78-91a0-4174-a515-fc81214e3dab\",\n  \"entity_type\": \"ACCOUNT_GROUP\",\n  \"entity_id\": \"413715f2-5401-4b97-8055-034a6b879f8c\",\n  \"role_type\": \"GUARDIAN\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Response","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"baf05386-0459-4e8c-9ac9-cd6442f194dd\",\n  \"created_at\": \"2025-04-01T10:11:40Z\",\n  \"updated_at\": \"2025-04-01T10:11:40Z\",\n  \"user_id\": \"9c36af78-91a0-4174-a515-fc81214e3dab\",\n  \"entity_type\": \"ACCOUNT_GROUP\",\n  \"entity_id\": \"413715f2-5401-4b97-8055-034a6b879f8c\",\n  \"role_type\": \"GUARDIAN\",\n  \"status\": \"INACTIVE\"\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-business-role-request","__idx":5},"children":["Example Business role request"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Request","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"user_id\": \"0d10c51f-33f2-4399-b8ab-92ec84e6b2f0\",\n  \"entity_type\": \"BUSINESS\",\n  \"entity_id\": \"6deb17c8-950e-4377-b500-5522af5ef712\",\n  \"role_type\": \"LEGAL_REPRESENTATIVE\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Response","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"e8b5a51d-8baf-4d0b-8a3b-8f8f8f8f8f8f\",\n  \"created_at\": \"2025-04-01T10:11:40Z\",\n  \"updated_at\": \"2025-04-01T10:11:40Z\",\n  \"user_id\": \"0d10c51f-33f2-4399-b8ab-92ec84e6b2f0\",\n  \"entity_type\": \"BUSINESS\",\n  \"entity_id\": \"6deb17c8-950e-4377-b500-5522af5ef712\",\n  \"role_type\": \"LEGAL_REPRESENTATIVE\",\n  \"status\": \"ACTIVE\"\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"listing-roles","__idx":6},"children":["Listing roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can retrieve a list of all created roles by submitting the following GET request:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["GET /roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also retrieve details for a specific /role using the following:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["GET /roles/{role_id}"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"user-roles-status","__idx":7},"children":["User roles status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When assigning or retrieving  users’ roles, the following statuses appear in the response message."]},{"$$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":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["PENDING"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The role is not yet activated. This may occur if the account group requirements are not met. For example: A child account does not have at least two guardians assigned when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custody_type=JOINT_CUSTODY"]},".  A business account does not have at least one legal representative and one ultimate business owner assigned."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["ACTIVE"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The role is active and mapped to the user and account group/business."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["DEACTIVATED"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The role is deactivated. For example, a guardian’s role deactivates when the child user comes of age."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"roles-event-webhooks","__idx":8},"children":["Roles event webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use the Roles event webhook to track the status of the roles creation. Both the account group role and business role events use the following statuses:"]},{"$$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":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["ROLE.CREATED"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The role is added to the system but not yet activated. This may occur if the account group requirements are not met."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["ROLE.ACTIVATED"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The role is active and mapped to the user and account group/business."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["ROLE.DEACTIVATED"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The role is deactivated. For example, a guardian’s role deactivates when the child user comes of age."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response-account-group-role-creation","__idx":9},"children":["Example response account group role creation"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Response","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{  \n  \"id\": \"2df83681-6a42-4837-a554-a8197335bcfa\",  \n  \"created_at\": \"2021-11-22T09:04:42Z\",  \n  \"type\": \"ROLE.CREATED\",  \n  \"object\": {  \n    \"id\": \"baf05386-0459-4e8c-9ac9-cd6442f194dd\",  \n    \"created_at\": \"2025-04-01T10:11:40Z\",  \n    \"updated_at\": \"2025-04-01T10:11:40Z\",  \n    \"user_id\": \"9c36af78-91a0-4174-a515-fc81214e3dab\",  \n    \"entity_type\": \"ACCOUNT_GROUP\",  \n    \"entity_id\": \"413715f2-5401-4b97-8055-034a6b879f8c\",  \n    \"role_type\": \"GUARDIAN\",  \n    \"custody_type\": \"JOINT_CUSTODY\",  \n    \"status\": \"PENDING\"  \n  },  \n  \"webhook_id\": \"1b097e06-8a14-4181-b72a-de0972a3c57b\"  \n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response-business-role-activation","__idx":10},"children":["Example response business role activation"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Response","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{  \n  \"id\": \"2df83681-6a42-4837-a554-a8197335bcfa\",  \n  \"created_at\": \"2021-11-22T09:04:42Z\",  \n  \"type\": \"ROLE.ACTIVATED\",  \n  \"object\": {  \n    \"id\": \"e8b5a51d-8baf-4d0b-8a3b-8f8f8f8f8f8f\",  \n    \"created_at\": \"2025-04-01T10:11:40Z\",  \n    \"updated_at\": \"2025-04-01T10:11:40Z\",  \n    \"user_id\": \"0d10c51f-33f2-4399-b8ab-92ec84e6b2f0\",  \n    \"entity_type\": \"BUSINESS\",  \n    \"entity_id\": \"6deb17c8-950e-4377-b500-5522af5ef712\",  \n    \"role_type\": \"LEGAL_REPRESENTATIVE\",  \n    \"status\": \"ACTIVE\"  \n  },  \n  \"webhook_id\": \"1b097e06-8a14-4181-b72a-de0972a3c57b\"  \n}\n","lang":"json"},"children":[]}]}]}]},"headings":[{"value":"Creating user roles","id":"creating-user-roles","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Setting the user’s role","id":"setting-the-users-role","depth":2},{"value":"Examples request and response for child accounts","id":"examples-request-and-response-for-child-accounts","depth":2},{"value":"Example Account Group role request","id":"example-account-group-role-request","depth":3},{"value":"Example Business role request","id":"example-business-role-request","depth":3},{"value":"Listing roles","id":"listing-roles","depth":2},{"value":"User roles status","id":"user-roles-status","depth":2},{"value":"Roles event webhooks","id":"roles-event-webhooks","depth":2},{"value":"Example response account group role creation","id":"example-response-account-group-role-creation","depth":3},{"value":"Example response business role activation","id":"example-response-business-role-activation","depth":3}],"frontmatter":{"seo":{"title":"Creating user roles"}},"lastModified":"2026-04-21T11:55:46.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/byol/guides/users/users_onboarding_roles","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}