Create BPO Account

The Brokerage API provides a way for you to manage brokerage BPO accounts for your users.

Overview

This document will walk you through the following steps in order to create a BPO user account:

Create person.
Create BPO account using the person.

This document will walk you through the process of creating a new BPO user account on the lemon.markets brokerage platform. To ensure high compatibility with your development setup, we will discuss the API interface of lemon.markets while using the command line utilities curl and jq. If you use an auto-generated API client (e.g. from our OpenAPI description) or an HTTP client in a programming language, you should be able to adapt these examples to your needs.

Preparations: Create person profile

In order to create a BPO user account a person needs to be created.

curl -sS \
  -H 'LMG-Data-Privacy-Access-Principal: backend-nobody' \
  -H 'LMG-Data-Privacy-Access-Justification: open_account' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -X POST \
  'https://sandbox.api.lemon.markets/v1/persons' \
  -d '{
    "date_of_birth": "1964-08-13",
    "email": "[email protected]",
    "firstname": "Erika",
    "lastname": "Mustermann",
    "nationalities": [
      "DE"
    ],
    "phone_number": "+49172997318",
    "place_of_birth": {
      "city": "Berlin",
      "country": "DE"
    },
    "registered_address": {
      "city": "Köln",
      "country": "DE",
      "line_1": "Heidestraße 17",
      "postal_code": "51147"
    },
    "tax_residencies": [
      {
        "country": "DE"
      }
    ]
  }' | jq

Which should result in a response like this:

{
  "date_of_birth": "1964-08-13",
  "email": "[email protected]",
  "firstname": "Erika",
  "id": "pers_9aa38d16cb1e436baf48381906057964",
  "lastname": "Mustermann",
  "nationalities": [
    "DE"
  ],
  "phone_number": "+49172997318",
  "place_of_birth": {
    "city": "Berlin",
    "country": "DE"
  },
  "registered_address": {
    "city": "Köln",
    "country": "DE",
    "line_1": "Heidestraße 17",
    "line_2": null,
    "postal_code": "51147"
  },
  "tax_residencies": [
    {
      "country": "DE",
      "tax_identification_number": null
    }
  ]
}

For more details, see our API reference:
Create Person.

Collect User Information

Now that we have created a person profile we we need to use the person id to create a BPO account.

Create User Account Reference

In order to have a reference for the user, we need to create an account.

curl -X POST 'https://sandbox.api.lemon.markets/v1/accounts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'content-type: application/json' \
  -H 'LMG-Data-Privacy-Access-Principal: backend-erika.mustermann%40example.com' \
  -H 'LMG-Data-Privacy-Access-Justification: open_account' \
  -d '{
    "customer": {
      "type": "person",
      "id": "pers_9aa38d16cb1e436baf48381906057964"
    },
    "accepted_agreements": [],
    "declaration_of_acting_on_own_account": true
  }' | jq

This will return a similar response object. We will focus on the added property id. In subsequent steps, we'll use
that identifier to refer to the account as is being set up:

{
  "id": "cusa_c2c3f89ec0524b6e818ce00c16e4897f",
  "cash_account": null,
  "customer": {
    …
  },
  "declaration_of_acting_on_own_account": true,
  "history": [
    {
      "status": "created",
      "timestamp": "2023-06-29T14:43:03.937676+00:00"
    }
  ],
  "securities_account": null,
  "status": "created"
}

For more details, see our API reference: Create Account.

Inspect Onboarding Checks

With our account identifier we can now check which parts of the onboarding process are still pending:

curl --request GET \
     --url https://sandbox.api.lemon.markets/v1/accounts/cusa_c2c3f89ec0524b6e818ce00c16e4897f/checks \
     --header 'LMG-Data-Privacy-Access-Justification: onboarding.check_status' \
     --header 'LMG-Data-Privacy-Access-Principal: backend-cusa_c2c3f89ec0524b6e818ce00c16e4897f' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer lP9y2II79cpPC3ie7lrHCmYcMWMsoTId'

This will provide us with a response like this:

{
  "data": [
    {
      "data": null,
      "history": [
        {
          "status": "processing",
          "timestamp": "2023-06-29T14:43:03.937676+00:00"
        }
      ],
      "status": "processing",
      "type": "risk_assessment"
    },
    {
      "data": null,
      "history": [
        {
          "status": "action_required",
          "timestamp": "2023-06-29T14:43:03.937676+00:00"
        }
      ],
      "status": "action_required",
      "type": "experience"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}

For more details, see our API reference:
Get Onboarding Checks.

Wait for all Checks to Complete

In order to detect when the account opening process was successful, you can issue periodic calls to inspect the
onboarding checks as outlined below. To avoid the downside of making the user wait longer than required, we recommend
to set up a webhook handler which can notify the application once the account.created event arrives for the account ID.

Query the New Account

After the account was opened, you can check the full metadata for the account, including the information required to
make a deposit.

curl --request GET \
     --url https://sandbox.api.lemon.markets/v1/accounts/cusa_c2c3f89ec0524b6e818ce00c16e4897f \
     --header 'LMG-Data-Privacy-Access-Justification: onboarding.display_cash_account' \
     --header 'LMG-Data-Privacy-Access-Principal: backend-cusa_c2c3f89ec0524b6e818ce00c16e4897f' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer lP9y2II79cpPC3ie7lrHCmYcMWMsoTId'

This will provide you with the following data points:

{
  "id": "cusa_20323d55bb264d42b0b225d293591049",
  "cash_account": {
    "bic": "BYLADEM1001",
    "iban": "DE02120300000000202051"
  },
  "customer": {
    …
  },
  "declaration_of_acting_on_own_account": true,
  "history": [
    {
      "status": "opened",
      "timestamp": "2023-06-12T17:34:27.865542+00:00"
    },
    {
      "status": "created",
      "timestamp": "2023-06-12T17:23:16.975969+00:00"
    }
  ],
  "securities_account": {
    "number": "000000044"
  },
  "status": "opened"
}

You can see the status changed to opened, the history has a second element and the cash account property is populated.

For more details, see our API reference: Get Account.

Sequence Diagram

Congratulations to completing this tutorial. Here's a simplified schema of the process that can help you when
implementing this process in your product.

Sequence Diagram for BPO Account Onboarding