Create Business Account
This page will help you get familiar with the endpoints to create a business account.
This guide walks you through the process of onboarding an eligible business customer (eligible per lemon.markets’ eligibility conditions) onto the lemon.markets platform using our APIs. This applies to partners where lemon.markets will perform the KYC on the prospective end customer.
Introduction
Onboarding a business customer is a multi-stage journey. It starts with gathering essential information about the business itself, understanding who its key individuals are (like Legal Representatives and Beneficial Owners), ensuring all necessary legal agreements are in place, and culminates in the creation of their official customer account with us. This guide serves as a roadmap, where each step often uses information (like unique IDs) received from the previous API calls. It outlines the process step-by-step.
Prerequisites
Authorization
Before you make any calls, remember that all API requests must be authenticated. Please refer to our Authorization Guide for detailed instructions on how to include your API key and the necessary data privacy headers (LMG-Data-Privacy-Access-Principal, LMG-Data-Privacy-Access-Justification) in your requests.
Onboarding Flow Overview
The general flow for onboarding a business customer is as follows:
- Fetch Current Agreements
- Create the Business Entity
- Manage Associated Persons (Create Person Records, Add Legal Representatives, Add Beneficial Owners)
- Create the Customer Account
Let's dive into each step!
1. Fetching Agreements
Prior to data collection, it is essential to fetch the latest versions of all relevant legal agreements. The business and its representatives will need to review and accept these. For business accounts, this usually means our Privacy Policy, Terms & Conditions, and the current Pricing Table.
You can fetch these with a simple GET request:
curl -sS \
-H 'LMG-Data-Privacy-Access-Principal: your-service-user' \
-H 'LMG-Data-Privacy-Access-Justification: onboarding.fetch_agreements' \
-H 'Authorization: Bearer <Your-API-Key>' \
'https://api.lemon.markets/v1/agreements' | jq
The API will return a list of agreement objects. Each one will have an id, type, url (where you can find the actual document), language, and name.
An example of the response that you would receive:
{
"data": [
{
"id": "agr_00b02201f32344e9be4ea0df15ca88ad",
"type": "pricing_table",
"url": "https://agreements.lemon.markets/test-document.pdf",
"language": "de",
"name": "Preis- und Leistungsverzeichnis"
},
{
"id": "agr_7fdbaf3c40e54629bf37d7d68eff57e5",
"type": "privacy_policy",
"url": "https://agreements.lemon.markets/test-document.pdf",
"language": "de",
"name": "Datenschutzerklärung"
},
{
"id": "agr_fdba24558c3a48ce9b21f2e2fc1c706b",
"type": "terms_and_conditions",
"url": "https://agreements.lemon.markets/test-document.pdf",
"language": "de",
"name": "Kundenvereinbarung"
}
],
"pagination": {
"next_cursor": null
}
}
The id (hereafter referred to as agreement_id) for the Privacy Policy, Terms & Conditions, and Pricing Table should be stored for use in subsequent steps.
2. Creating the Business Entity
This step involves submitting the core details of the business entity being onboarded.
API Endpoint: POST /v1/businesses
It is recommended to provide complete information about the business, including its registration details, industry, address, tax information and financial standing. Accurate and complete data facilitates a quicker and smoother onboarding process.
{
"name": "DuckBiz GmbH - Holding",
"registration": {
"legal_form": "gmbh",
"id": "HRB 99999",
"court": "Charlottenburg",
"incorporation_country": "DE",
"incorporation_date": "2000-01-01"
},
"industry": {
"nace_rev": "2.1",
"code": "A.3.30"
},
"registered_address": {
"line_1": "Kottbusser Damm 79",
"line_2": "Innenhof 2",
"postal_code": "10709",
"city": "Berlin",
"country": "DE"
},
"taxation_countries": [
{
"country": "DE",
"tax_number": "68 034 152 756",
"vat_id": "DE0817"
}
],
"fatca_relevant": false,
"single_tier_ownership": true,
"nfe_type": "active",
"expected_annual_revenue": "9605030",
"last_year_revenue": "80000",
"currency": "EUR"
}
Upon successful creation, the API returns the full business entity object, including a unique id (e.g., le_...). This id (hereafter business_id) uniquely identifies this business and is critical for linking associated persons and for the final account creation.
{
"id": "le_873c612bad9a45cd9a45471b1a3bc293",
"name": "DuckBiz GmbH - Holding",
"registration": {
"id": "HRB 99999",
"court": "Charlottenburg",
"legal_form": "gmbh",
"incorporation_country": "DE",
"incorporation_date": "2000-01-01"
},
"industry": {
"nace_rev": "2.1",
"code": "A.3.30"
},
"registered_address": {
"line_1": "Kottbusser Damm 79",
"line_2": "Innenhof 2",
"postal_code": "10709",
"city": "Berlin",
"country": "DE"
},
"taxation_countries": [
{
"country": "DE",
"tax_number": "68 034 152 756",
"vat_id": "DE0817",
"business_identification_number": null
}
],
"fatca_relevant": false,
"expected_annual_revenue": "9605030.00",
"last_year_revenue": "80000.00",
"currency": "EUR",
"legal_entity_identifier": null,
"single_tier_ownership": true,
"nfe_type": "active"
}
3. Managing Associated Persons (Legal Representatives & Beneficial Owners)
Businesses are run by people! So, the next phase is about creating records for the individuals connected to the business and defining their roles.
3a. Creating Person Records
For every individual who will act as a Legal Representative or has been identified as a Beneficial Owner, you'll need to create a Person record first. This creates a reusable profile for that individual.
API Endpoint: POST /v1/persons
The request should include the individual's personal details and, importantly, confirmation of their acceptance of the Privacy Policy (using the agreement_id obtained in Step 1).
{
"firstname": "Leona",
"lastname": "Lemon-Ade",
"date_of_birth": "1990-01-01",
"registered_address": {
"line_1": "Heidestraße 15",
"line_2": "Haus B",
"city": "Berlin",
"postal_code": "10709",
"country": "DE"
},
"tax_residencies": [
{
"country": "DE",
"tax_identification_number": "12 908 676 460"
}
],
"accepted_agreements": [
{
"agreement_id": "{{privacy_policy_id}}",
"accepted_at": "{{iso_timestamp}}"
}
],
"email": "[email protected]",
"phone_number": "+49123456789"
}
Replace {{privacy_policy_id}} with the actual ID for the Privacy Policy and {{iso_timestamp}} with the current timestamp in ISO-8601 format (e.g., 2025-05-12T23:10:30.366Z).
The API will return a unique id for the person (e.g., pers_...). This id (hereafter person_id) is then used to link this individual to the business in their specific role.
{
"id": "pers_dfd9f4c19f5f444f855a2635c5d86890",
"firstname": "Leona",
"lastname": "Lemon-Ade",
"date_of_birth": "1990-01-01",
"registered_address": {
"line_1": "Heidestraße 15",
"line_2": "Haus B",
"postal_code": "10709",
"city": "Berlin",
"country": "DE"
},
"nationalities": [
"DE"
],
"email": "[email protected]",
"phone_number": "+49123456789",
"place_of_birth": {
"city": "Berlin",
"country": "DE"
},
"tax_residencies": [
{
"country": "DE",
"tax_identification_number": "12908676460"
}
]
}
Repeat this step for all relevant individuals.
3b. Adding Legal Representative(s)
With the person records created, they can now be linked to the business as Legal Representatives.
API Endpoint: POST /v1/businesses/{{business_id}}/legal-representatives
Replace {{business_id}} with the ID obtained in Step 2.
The request requires the person_id (from Step 3a) and the individual's representation rule (e.g., sole_representation).
{
"person": "pers_dfd9f4c19f5f444f855a2635c5d86890",
"representation_rule": "sole_representation"
}
The API returns a unique id (e.g., rep_…). This id (hereafter legal_representative_id) is required for the final account creation step, as legal representatives accept further agreements on behalf of the business.
{
"id": "rep_9cf6c6d1045b471f9f0987dce3f5e8fd",
"person": "pers_dfd9f4c19f5f444f855a2635c5d86890",
"representation_rule": "sole_representation"
}
Make sure this step is repeated for every legal representative.
3c. Adding Beneficial Owner(s)
Similarly, link individuals identified as Beneficial Owners to the business.
API Endpoint: POST /v1/businesses/{{business_id}}/beneficial-owners
Replace {{business_id}} with the ID obtained in Step 2.
The request includes the person_id and details about their share and voting rights percentages.
{
"person": "pers_dfd9f4c19f5f444f855a2635c5d86890",
"shares_pct": "100.000",
"voting_rights_pct": "100.000",
"nature": "real"
}
The API returns the created record with a unique id for this beneficial owner (e.g., ubo_...).
{
"id": "ubo_1198b7a63fb846ca97c9996787ae2418",
"person": "pers_dfd9f4c19f5f444f855a2635c5d86890",
"shares_pct": "100.00000",
"voting_rights_pct": "100.00000",
"nature": "real"
}
Repeat this for all beneficial owners.
4. Creating the Customer Account
This final API call formalizes the customer account by consolidating the business entity and the acceptance of the remaining agreements (Terms & Conditions, Pricing Table) by the legal representative(s).
API Endpoint: POST /v1/accounts
This payload connects the business entity (using its business_id) with the acceptance of the Terms & Conditions and Pricing Table. These agreements must be accepted by the authorized legal representative(s).
{
"customer": {
"type": "business",
"id": "{{business_id}}"
},
"declaration_of_acting_on_own_account": true,
"accepted_agreements": [
{
"agreement_id": "{{terms_conditions_id}}",
"accepted_at": "{{iso_timestamp}}",
"legal_representative": "{{lr_id_1}}"
},
{
"agreement_id": "{{pricing_table_id}}",
"accepted_at": "{{iso_timestamp}}",
"legal_representative": "{{lr_id_1}}"
}
// If you have multiple legal representatives who need to accept,
// you'll include separate entries for each LR's acceptance of each required agreement.
// For example, if a second LR also needs to accept the Terms & Conditions:
// {
// "agreement_id": "{{terms_conditions_id}}",
// "accepted_at": "{{iso_timestamp}}",
// "legal_representative": "{{lr_id_2}}"
// }
]
}
Note:
{{business_id}}is from Step 2.{{terms_conditions_id}}and{{pricing_table_id}}are the agreement IDs from Step 1.{{lr_id_1}}(and{{lr_id_2}}, etc.) is thelegal_representative_id(rep_...) obtained in Step 3b for each legal representative accepting the agreements. All legal representatives authorized to act on behalf of the business must accept these agreements.
Upon successful submission and validation, the API returns details of the newly created customer account, including its initial status.
{
"id": "cusa_6375dfce1f2d4ae7badbac72da14ae8a",
"status": "created",
"history": [
{
"status": "created",
"timestamp": "2025-05-12T21:03:12.505271+00:00"
}
],
"reference_account": null,
"cash_account": null,
"securities_account": null,
"declaration_of_acting_on_own_account": true,
"customer": {
"type": "business",
"id": "{{business_id}}"
},
"identifications": []
}
Sequence Diagram
A visual sequence diagram illustrating the interactions between the business being onboarded, the partner system and the lemon.markets API is shown below.
Next Steps
Once the customer account is in the created state, lemon.markets performs necessary due diligence and verification checks. You will be notified of status changes via webhooks (if configured), or you can poll the account status using the GET /v1/accounts/{account_id} API endpoint.
We provide webhooks for various account events, including:
account.closedaccount.createdaccount.openedaccount.rejected
After successful verification, the account status will typically move to opened. At this point, the business customer can utilize the full range of brokerage functionalities, such as funding their account and placing trades.
Updated 8 days ago