# Creating a user

To create a user, follow the steps described below.

## Collect the user's data

First, collect the user data, such as name, birthdate, email address, address and other data (see full list of required and optional data in the [API reference](/api/users/create_user)), 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.
- It must be verified that the address actually exists and that it matches the address indicated either in the identification documents or in a separate proof of residency at a later stage of the onboarding process.
- A user must have at least one nationality. If a user has multiple nationalities, all nationalities need to be submitted.


## Submit the user's data

Send the user's personal information with the following request:

**POST** [`/users`](/api/users/create_user)

**Example**

Example request
{
  "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"
  ],
  "phone_number": "4930901820",
  "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"
  },
  "fatca": {
    "status": false,
    "confirmed_at": "2020-08-24T14:15:22Z"
  },
  "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"
  }
}
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",
  "nationalities": [
    "DE",
    "AU"
  ],
  "phone_number": "4930901820",
  "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"
  },
  "fatca": {
    "status": false,
    "confirmed_at": "2020-08-24T14:15:22Z"
  },
  "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"
  },
  "status": "ACTIVE",
  "branch_id": "e6373bfa-ff12-4004-8de9-747ac96764da"
}
In response to the successful creation of a user, you will receive a user ID, which you will need for regulatory checks and all further operations. You will also receive a webhook with the respective [user created event](/api/users/user_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](/api_errors) 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](/products/tol/guides/branches) here.

## Listing users

You can list all users with **GET** [`/users`](/api/users/).

To retrieve a single user call **GET** [`/users/{user_id}`](/api/users/retrieve_user) 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",
  "nationalities": [
    "DE",
    "AU"
  ],
  "phone_number": "4930901820",
  "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"
  },
  "fatca": {
    "status": false,
    "confirmed_at": "2020-08-24T14:15:22Z"
  },
  "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"
  },
  "status": "ACTIVE"
}
## Status of a user

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. |