Skip to content
Documentation
/
/
/
User data change

User data change

A user might request a data change when, for example, moving to a new city or getting married and thus changing their name or adding a nationality.

This guide outlines how to use the Investment API to change user data and the proof documents that must be provided in support of these changes.

Prerequisites

Before you can change data of a user you must have created one. You can find out how to do this in our User onboarding guide.

When requesting user data changes, you must submit each separate request individually and wait for the corresponding webhook event (USER.DATA_CHANGED or USER.DATA_CHANGE_FAILED) before submitting the next request.

Submitting requests in bulk can result in errors during the process.

Changing user data

In the request body, you specify which fields you intend to change. Request a change by sending:

POST /users/{user_id}/data_change_requests

The API responds with 202 Accepted and processes the change asynchronously. Upvest confirms the outcome with a USER.DATA_CHANGED or USER.DATA_CHANGE_FAILED webhook event.

Depending on the respective fields to be changed, Upvest may require a proof for changing the user information. There are four different categories available that require different proof documents.

The following proof documents are accepted:

CategoryUser fieldsRequired proof documents
Name changefirst_name, middle_name, last_name
  • PASSPORT - Passport
  • ID_CARD - National Identification document
Nationality changenationalities (array)
  • PASSPORT - Passport
  • ID_CARD - National Identification document
Address changeaddress (object)
  • UTILITY_BILL - Utility bill
  • TELEPHONE_BILL - Telephone bill
  • INTERNET_BILL - Internet bill
  • BANK_STATEMENT - Bank statement
  • REGISTRATION_CERT - Registration certificate
  • RESIDENCE_PERMIT - Residence permit
  • ID_CARD - National Identification document
Othersalutation, title, email, phone_number, birth_name, postal_address, branch_id, gender, social_security_number, tags, decease_date, terms_and_conditions, data_privacy_and_sharing_agreement
  • N/A

Changing the user's name

Changing a user's name requires either a passport or national ID card. Upload the document to your data transfer bucket and include its issuance_date, its URL (data_download_link), and the document_type in the request.

Example request

{
  "first_name": "Karl",
  "last_name": "Schmidt",
  "issuance_date": "2030-01-01",
  "data_download_link": "https://bucket.customer.com/ident/user3.zip",
  "document_type": "ID_CARD"
}

Changing the user's nationality

Changing a user's nationality requires either a passport or national ID card. Upload the document to your data transfer bucket and include its issuance_date, its URL (data_download_link), and the document_type in the request.

Example request

{
  "nationalities": [
    "DE"
  ],
  "issuance_date": "2030-01-01",
  "data_download_link": "https://bucket.customer.com/ident/user3.zip",
  "document_type": "ID_CARD"
}

Changing the user's address

Changing a user's address requires one of the forms of evidence listed above. Upload the document to your data transfer bucket and include its issuance_date, its URL (data_download_link), and the document_type in the request.

Example request

{
  "address": {
    "address_line1": "Rosenweg 221",
    "address_line2": "apt. 33",
    "postcode": "45678",
    "city": "Berlin",
    "state": "BE",
    "country": "DE"
  },
  "issuance_date": "2020-01-01",
  "data_download_link": "https://bucket.customer.com/por/user3.zip",
  "document_type": "UTILITY_BILL"
}

Changing other user details

Changing other user details, such as the email address, phone number or salutation, doesn't require additional evidence to be provided. This example show a simple request to change a user's email address.

Example request

{
  "email": "max@example.com"
}

Changing the user's consents

A user might need to accept new Terms and Conditions or a new Data Privacy and Sharing Agreement. For example, this occurs when a child user turns 18 accepts the Terms and Conditions and Data Privacy and Sharing Agreement as an adult.

You can send terms_and_conditions, data_privacy_and_sharing_agreement, or both. Each consent you send replaces the user's existing consent of the same type. Any consent you leave out remains unchanged.

Each consent requires the following fields:

  • consent_document_id: The ID of the required consent document configured for your setup.
  • confirmed_at: The time the user accepted the document. It cannot be in the future.

If a consent document isn't configured, the data change fails and you receive a USER.DATA_CHANGE_FAILED webhook event.

After the change, Upvest checks the user's pending roles again. If a role was waiting only for these consents, Upvest activates it and you receive a ROLE.ACTIVATED webhook event.

Example request

{
  "terms_and_conditions": {
    "consent_document_id": "d0b83880-3809-4eee-b0df-ca50db84c15a",
    "confirmed_at": "2020-08-24T14:14:22Z"
  },
  "data_privacy_and_sharing_agreement": {
    "consent_document_id": "7ab0fc5c-8157-4acd-b02d-6ccda0e81dec",
    "confirmed_at": "2020-08-24T14:16:22Z"
  }
}

After you requested a data change Upvest will download a potential proof for the data change, adjust the user information and then send a data change passed webhook. If the data change failed, e.g. due to problems with the proof files, you will receive a data change failed webhook.

Next steps

Since a change to user data can made at any point in the user's lifecycle in the Investment API, a next step could be to create an account group or place an order. You can see the updated data when retrieving a report.