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.
- Terms and conditions and data privacy acknowledgements are transferred digitally via the Investment API. We rely on you to submit the timestamp of the user's acknowledgement event during your onboarding process and a version ID of the documents, which is linked to the PDF documents.
Send the user's personal information with the following request:
POST /users
Example
{
"first_name": "Karl",
"last_name": "Schmidt",
"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"
}
}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",
"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"
},
"status": "ACTIVE"
}The following status apply to a user:
| 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 full functionality of the Investment API is accessible. |
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. |