# Create a role Creates a role. Endpoint: POST /roles Version: 1.111.0 Security: oauth-client-credentials ## Header parameters: - `upvest-client-id` (string, required) Tenant Client ID Example: "363f3305-7ab0-4e82-a158-f9d382ad08b6" - `Authorization` (string, required) Bearer (access) token from the OAuth flow with correct scopes. https://datatracker.ietf.org/doc/html/rfc6750 Example: "Bearer c2VjcmV0Cg==" - `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 - `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 Example: "ccb07f42-4104-44ad-8e1f-c660bb7b269c" - `upvest-api-version` (string) Upvest API version (Note: Do not include quotation marks) Enum: "1" ## Request fields (application/json): - `body` (object) — one of: - Account Group Role - Create - Request: - `user_id` (string, required) User unique identifier. - `entity_type` (string, required) Entity type must be ACCOUNT_GROUP - `entity_id` (string, required) Account group unique identifier. - `role_type` (string, required) Role type for account group. * GUARDIAN - Guardian for child account groups Enum: "GUARDIAN" - `custody_type` (string) Custody type for child account groups. * SOLE_CUSTODY - Single guardian * JOINT_CUSTODY - Multiple guardians required Enum: "SOLE_CUSTODY", "JOINT_CUSTODY" - Business Role - Create - Request: - `user_id` (string, required) User unique identifier. - `entity_type` (string, required) Entity type must be BUSINESS - `entity_id` (string, required) Unique identifier for the business. - `role_type` (string, required) Role type for business entity. * LEGAL_REPRESENTATIVE - Legal representative of the business * AUTHORISED_SIGNATORY - Authorised signatory * ULTIMATE_BENEFICIAL_OWNER - Ultimate beneficial owner * CONTRACTING_EXECUTIVE - Contracting executive * TRADER - Trader Enum: "LEGAL_REPRESENTATIVE", "AUTHORISED_SIGNATORY", "ULTIMATE_BENEFICIAL_OWNER", "CONTRACTING_EXECUTIVE", "TRADER" ## Response 200 fields (application/json): - `body` (object) — one of: - Account Group Role - Create - Response: - `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) User unique identifier. - `entity_type` (string, required) Entity type must be ACCOUNT_GROUP - `entity_id` (string, required) Unique identifier of the entity a role is attached to. - `role_type` (string, required) Role type for account group. * OWNER - Account group owner * GUARDIAN - Guardian for child account groups * CHILD - Child user in a child account group Enum: "GUARDIAN", "OWNER", "CHILD" - `status` (string, required) Status of the role assignment. * PENDING - Role is not activated * ACTIVE - Role is active * DEACTIVATED - Role is deactivated Enum: "PENDING", "ACTIVE", "DEACTIVATED" - `custody_type` (string) Custody type for child account groups. * SOLE_CUSTODY - Single guardian * JOINT_CUSTODY - Multiple guardians required Enum: same as `custody_type` in "Account Group Role - Create - Request" (2 values) - Business Role: - `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) User unique identifier. - `entity_type` (string, required) Entity type must be BUSINESS - `entity_id` (string, required) Unique identifier of the entity a role is attached to. - `role_type` (string, required) Role type for business entity. * LEGAL_REPRESENTATIVE - Legal representative of the business * AUTHORISED_SIGNATORY - Authorised signatory * ULTIMATE_BENEFICIAL_OWNER - Ultimate beneficial owner * CONTRACTING_EXECUTIVE - Contracting executive * TRADER - Trader Enum: same as `role_type` in "Business Role - Create - Request" (5 values) - `status` (string, required) Status of the role assignment. * PENDING - Role is not activated * ACTIVE - Role is active * DEACTIVATED - Role is deactivated Enum: same as `status` in "Account Group Role - Create - Response" (3 values) ## 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 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 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 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 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 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 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 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.