To create a user, follow the steps described below.
First, collect name, birthdate, nationalities and residential address, as the minimum requirement, which have to satisfy the following conditions:
- It must not be a P.O. box (Post Office box) or c/o (in care of) address.
- The residential address must be validated on the client side to actually reflect a real address. This is relevant for downstream processes such as withholding tax calculation (i.e. church tax).
- A user must have at least one nationality. If a user has multiple nationalities, all nationalities need to be submitted.
- Add the end user's gender if they will open a German pension plan, like Altersvorsorgedepot, or a SIPP account in the United Kingdom.
While optional, you may need to collect end user email addresses for certain corporate actions like proxy voting.
Send the user's personal information with the following request:
POST /users
Example
{
"first_name": "Karl",
"last_name": "Schmidt",
"email": "karl.schmidt@example.com",
"salutation": "SALUTATION_MALE",
"title": "DR",
"birth_date": "1972-09-30",
"birth_city": "Berlin",
"birth_country": "DE",
"birth_name": "Schmidt",
"nationalities": [
"DE",
"AU"
],
"postal_address": {
"address_line1": "Rosenweg 221",
"address_line2": "apt. 33",
"postcode": "45678",
"city": "Berlin",
"state": "BE",
"country": "DE"
},
"address": {
"address_line1": "Rosenweg 221",
"address_line2": "apt. 33",
"postcode": "45678",
"city": "Berlin",
"state": "BE",
"country": "DE"
},
"tags": [
"CLIENT_EMPLOYEE"
]
}In response to the successful user creation, you will receive a user ID, which you will need to proceed with the account group creation and all further operations. You will also receive a webhook with the respective user created event.
Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.
Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.
Upvest has introduced branches to allow our clients to easily customise the services and user experience they offer to their users. Therefore, users can be assigned to a branch, for example, depending on their geographical market. The branch_id is an optional field and is only available after consultation with Upvest. Learn more about branches here.
You can list all users with GET /users.
To retrieve a single user call GET /users/{user_id} with the user ID you received after creation.
Example response
{
"id": "83d83ec2-d2ca-49ff-bbea-b92b5c3be202",
"created_at": "2021-07-21T14:10:00.00Z",
"updated_at": "2021-07-21T14:10:00.00Z",
"first_name": "Karl",
"last_name": "Schmidt",
"email": "karl.schmidt@example.com",
"salutation": "SALUTATION_MALE",
"title": "DR",
"birth_date": "1972-09-30",
"birth_city": "Berlin",
"birth_country": "DE",
"birth_name": "Schmidt",
"decease_date": null,
"nationalities": [
"DE",
"AU"
],
"postal_address": {
"address_line1": "Rosenweg 221",
"address_line2": "apt. 33",
"postcode": "45678",
"city": "Berlin",
"state": "BE",
"country": "DE"
},
"address": {
"address_line1": "Rosenweg 221",
"address_line2": "apt. 33",
"postcode": "45678",
"city": "Berlin",
"state": "BE",
"country": "DE"
},
"status": "ACTIVE",
"tags": [
"CLIENT_EMPLOYEE"
]
}Deprecated: The user status field is deprecated — do not build new integrations on it.
To know when a user has met the onboarding requirements for an account group or business, listen for the ROLE.ACTIVATED webhook event of the user's role (for example, the OWNER role for a PERSONAL account group). See Role-based activation.
The user status field can still return the following values:
| Status | Description |
|---|---|
INACTIVE | The user's approval is pending - the user is visible via our API but cannot be processed. |
ACTIVE | User is active. The actions the user can perform are scoped by the role(s) assigned to them — see Creating user roles. |
OFFBOARDING | The offboarding of the user is initiated - the prerequisites are being checked continuously. |
OFFBOARDED | User is offboarded - the user's record can be kept for the regulatory period. |