Key Endpoints
- Create a Legal Entity Account
- Trigger an Onboarding
- Resume an Onboarding
- Manage an Onboarding
- Get Documents
- Upload Documents
Endpoints for Online Onboarding for Legal Entities
Note
When passing the token in the header for Online Onboarding, make sure to use "Bearer" with a capital “B”
Using Authorization: bearer (with a lowercase "b") will result in a 403 Forbidden error.
Operations | Endpoints | Description |
---|---|---|
Create an Account | POST | Provision a new legal entity account. |
Trigger Onboarding |
| If the account’s profile status is |
Resume Onboarding | GET | Resume a previously-started, in-progress onboarding. |
List All Accounts | GET | Retrieve a list of all accounts. |
Retrieve Specific Account | GET | Fetch details for a single account by its unique ID. |
Get Documents | GET | Retrieve a list of all documents. |
Upload Documents | POST | Upload a document associated with a legal entity currently being onboarded. |
1. Create a Legal Entity Account
Description: Establish a new legal entity account by providing necessary entity and representative details.
Request Parameter: An account object containing an legal-entity field with the details.
Endpoint: POST /accounts/legal-entity
Resource: account (subtype: legal-entity)
1.1 Payload
It creates or initiates the onboarding process for a legal entity, specifying:
- The legal entity's details
- The identity of its legal representative
- The type of relationship/profile (e.g., project holder)
- A linked wallet/account ID
{
"legalEntity": {
"name": "Example Company",
"type": "COMPANY",
"registrationNumber": "123456789",
"registrationCountry": "FR",
"registrationDate": "2000-01-01"
},
"legalRepresentative": {
"firstName": "John",
"lastName": "Doe",
"birthDate": "1980-06-15",
"email": "[email protected]",
"address": {
"country": "FR"
},
"birthCountry": "FR",
"nationalities": ["FR"]
},
"profile": "PROJECT_HOLDER",
"walletId": "4546767"
}
1.2 Parameters
Field | Required | Description | Type | Example | |
---|---|---|---|---|---|
name | Yes | Legal entity name | String | "Example Company" | |
type | Yes | Type of legal entity | Enum | "COMPANY" | |
registrationNumber | Yes | Registration number of the entity | String | "123456789" | |
registrationCountry | Yes | Country of registration (ISO 2-letter code) | String | "FR" | |
registrationDate | Yes | Date of registration (YYYY-MM-DD) | Date | "2000-01-01" | |
firstName | Yes | Representative's first name | String | "John" | |
lastName | Yes | Representative's last name | String | "Doe" | |
birthDate | Yes | Representative's birth date (YYYY-MM-DD) | Date | "1980-06-15" | |
email | Yes | Representative's email address | String | "[email protected]" | |
address.country | Yes | Representative's country of residence (ISO code) | String | "FR" | |
birthCountry | Yes | Representative's country of birth (ISO code) | String | "FR" | |
nationalities | Yes | Representative's nationalities (ISO codes) | Array | ["FR"] | |
profile | Yes | Profile type | Enum | "PROJECT_HOLDER" | |
walletId | Yes | Unique wallet identifier | String | "unique-wallet-id" | ([Lemonway Documentation][3], [Lemonway Support Center][4], [ADNews][2], [daswritingservices.com][5], [Lemonway Documentation][6], [Lemonway Documentation][7], [THE ORG][8], [Bit.ai][9], [Lemonway Documentation][10]) |
2. Trigger an Onboarding
Description: If the new account’s profile status is awaiting information, begin the online onboarding flow by calling the endpoint.
Request Body: An Account object containing an entity field with the entity details.
Endpoints:
- Company:
POST /onboardings/company
- Association:
POST /onboardings/association
- Sole Trader:
POST /onboardings/sole_trader
Resource: onboardings (subtype: company, association, sole_trader )
2.1 Payload
Used to trigger the online KYC onboarding flow for a legal entity, and specify a redirect URL for post-onboarding redirection (likely to your platform or frontend app).
{
"id": "e29fc895-b1e1-4278-90e1-008fcb4ce433",
"onboardingId": "96ab33e9-2028-4b1e-bd78-357aae99a749",
"identity": {
"name": "Collins and Sons",
"type": "ASSOCIATION",
"registrationNumber": "921aperiam",
"registrationCountry": "FR",
"registrationDate": "2023-03-21"
},
"status": "CREATED",
"profiles": [
{
"id": "165d0a17-1044-48be-a24e-6824e13ad0bb",
"type": "PROJECT_HOLDER",
"status": {
"type": "UNDER_ANALYSIS",
"subStatus": null
},
"wallets": [
{
"id": "23519c68-978b-481a-a6ec-7dd159eaacd7",
"internalId": "",
"type": "PAYMENT_ACCOUNT"
}
]
}
],
"information": {
"name": "Ratke - Pouros",
"type": "ASSOCIATION",
"website": "https://bella.com",
"vatNumber": "752",
"description": "Activity description",
"registrationDate": "2024-07-18",
"legalForm": "NON_PROFIT_ORGANIZATION",
"NACEcode": "94.99",
"address": {
"street": "Elena Lodge",
"postalCode": "75000",
"city": "Kreigerburgh",
"country": "FR"
},
"taxCode": "taxCode",
"otherFundsDestinationCountries": {
"countries": [
"FR"
]
},
"entityFunds": [
"OTHER",
"MEMBERSHIP_FEES"
],
"entityFundsOther": "SUBVENTION_BIS",
"financialAsset": "FIRST_TIER",
"tradingAddress": {
"street": "653 Alexandrea Road",
"postalCode": "91",
"city": "South Antoniettaland",
"country": "FR"
},
"projects": [
{
"description": "The best project of the world",
"website": "http://hillard.com"
}
],
"performsProhibitedActivity": false,
"locatedinHighriskCountry": false,
"legalRepresentative": {
"firstName": "Tamia",
"lastName": "Leannon",
"birthDate": "1992-01-24T00:00:00.000Z",
"birthCity": "Greenside",
"birthCountry": "FR",
"nationalities": [
"FR"
],
"email": "[email protected]",
"phone": "+33678989860",
"city": "New Orenport",
"country": "FR",
"street": "Napoleon Camp",
"postalCode": "75001",
"roles": [
{
"role": "LEGAL_REPRESENTATIVE"
},
{
"role": "BOARD_MEMBER",
"boardMemberPositions": [
"PRESIDENT"
]
}
]
}
},
"type": "LEGAL_ENTITY",
"documents": [
{
"status": "VERIFIED",
"type": "ARTICLES_OF_ASSOCIATION",
"name": "0dbbb33b-d370-4def-8fbc-7b3dbea3f507.pdf",
"downloadUrl": "https://account.dev.lemonway.com/accounts/e29fc895-b1e1-4278-90e1-008fcb4ce433/documents/0dbbb33b-d370-4def-8fbc-7b3dbea3f507.pdf"
},
{
"status": "VERIFIED",
"type": "BOARD_MEMBERS_INFORMATION",
"name": "970bcb30-29ce-43f0-8f24-32b6aaab3e9b.pdf",
"downloadUrl": "https://account.dev.lemonway.com/accounts/e29fc895-b1e1-4278-90e1-008fcb4ce433/documents/970bcb30-29ce-43f0-8f24-32b6aaab3e9b.pdf"
}
],
"createdAt": "2025-05-21T14:18:18.366Z"
}
2.2 Parameters
Field | Required | Description | Type | Example | |
---|---|---|---|---|---|
accountId | Yes | Identifier of the created account | String | "account-id" | |
redirectUrl | Yes | URL to redirect after onboarding completion | String | "https://yourwebsite.com/callback" | |
legalEntity | Yes | Legal entity details | Object | See above | |
legalRepresentative | Yes | Representative's details | Object | See above | ([Lemonway Documentation][3], [Lemonway Documentation][11], [Lemonway Documentation][12], [Bit Blog][13], [LinkedIn][14], [Lemonway Documentation][1]) |
3. Resume Onboarding
Description: This endpoint is used when an end-user saves their progress and returns to the onboarding page at a later time.
Request Parameter: onboardingId must be provided in the path to identify the onboarding session.
Endpoint: GET /onboardings/{onboardingId}/resume
Resource: onboardings resume
4. Manage Onboarding
Description: Retrieve a list of all accounts associated with your organization.
Request Parameter:
- $skipToken:
- createdAt timestamp js value
- $skipDirection:
- prev
- next
Endpoint: GET /accounts
Resource: accounts
4.1 Response
{
"data": [
{
"id": "fc2096f6-8bcb-4d58-b041-1516b1f013ff",
"onboardingId": "758b1ca1-c066-458b-af15-7c724ce3bcc1",
"identity": {
"firstName": "Rachael",
"lastName": "Gerlach",
"email": "[email protected]",
"birthDate": "2019-06-01",
"birthCountry": "FR",
"residenceCountry": "FR",
"nationalities": [
"FR"
]
},
"status": "CREATED",
"profiles": [
{
"id": "70f848da-7693-44ea-8d35-2c6d68dcb531",
"type": "PROJECT_HOLDER",
"status": {
"type": "INFORMATION_COLLECTION_IN_PROGRESS",
"subStatus": null
},
"wallets": [
{
"id": "098e1f05-c68b-4fcc-b6ce-ddd870d33d10",
"internalId": "",
"type": "PAYMENT_ACCOUNT"
}
]
}
],
"type": "INDIVIDUAL",
"updatedAt": "2025-05-12T15:05:28.324Z",
"createdAt": "2025-05-12T15:05:10.370Z"
},
{
"id": "691cc8b5-9b4f-4580-b659-f39aa5e08669",
"onboardingId": "ea754721-786d-40cb-8d2d-78d310f5dadf",
"identity": {
"name": "Gorczany Group",
"type": "ASSOCIATION",
"registrationNumber": "788totam",
"registrationCountry": "FR",
"registrationDate": "2023-03-21"
},
"status": "CREATED",
"profiles": [
{
"id": "9276794f-9813-445c-ae76-079383da089c",
"type": "PROJECT_HOLDER",
"status": {
"type": "IDENTITY_VERIFICATION_IN_PROGRESS",
"subStatus": null
},
"wallets": [
{
"id": "436b3cc8-e2c4-44d6-aac3-da69b7100f52",
"internalId": "",
"type": "PAYMENT_ACCOUNT"
}
]
}
],
"type": "LEGAL_ENTITY",
"updatedAt": "2025-05-12T18:13:18.583Z",
"createdAt": "2025-05-12T18:12:37.605Z"
},
{
"id": "79b3d214-2a4d-4483-9ab1-47a2907a5c20",
"onboardingId": null,
"identity": {
"firstName": "Florent",
"lastName": "Valmy",
"email": "[email protected]",
"birthDate": "2002-03-09",
"birthCountry": "FR",
"residenceCountry": "FR",
"nationalities": [
"FR"
]
},
"status": "ACCEPTED",
"profiles": [
{
"id": "a16bab26-d39d-4f1f-9017-b2e11dee41a7",
"type": "DONOR",
"status": {
"type": "ACCEPTED",
"subStatus": null
},
"wallets": [
{
"id": "325423243",
"internalId": 568071,
"type": "TECHNICAL"
}
]
}
],
"type": "INDIVIDUAL",
"updatedAt": "2025-05-12T14:36:27.552Z",
"createdAt": "2025-05-12T14:36:07.535Z"
},
{
"id": "4d44607a-8ecd-4e07-91b0-3328c9007f87",
"onboardingId": null,
"identity": {
"name": "Kassulke Group CORP",
"type": "COMPANY",
"registrationNumber": "49recusandae",
"registrationCountry": "ES",
"registrationDate": "2024-05-17"
},
"status": "ACCEPTED",
"profiles": [
{
"id": "a409abf8-db79-4f59-9dd4-c19b39dcc374",
"type": "PROJECT_HOLDER",
"status": {
"type": "ACCEPTED",
"subStatus": null
},
"wallets": [
{
"id": "878c0ae2-bdc4-42a7-a671-38cf24c8a2e2",
"internalId": 568070,
"type": "PAYMENT_ACCOUNT"
}
]
}
],
"type": "LEGAL_ENTITY",
"updatedAt": "2025-05-12T09:51:52.895Z",
"createdAt": "2025-05-12T09:45:47.252Z"
}
],
"nextLink": "/accounts/?&$skipToken=1747042500653&$skipDirection=next",
"prevLink": ""
}
Description: Retrieve detailed information for a specific account using its unique identifier.
Request Parameter: id must be provided in the path to identify the account.
Endpoint: GET /accounts/{id}
Resource: accounts
4.2 Response
The when endpoint is called the following information is provided:
- Provides account information (id, identity, status)
- Provides the Onboarding status
- Profiles linked to this account
- Wallets linked to this profile
{
"id": "f9137a42-20ca-40b0-8492-07b4eb45907b",
"onboardingId": "39e940a5-357f-4863-a549-7605183a4d44",
"identity": {
"firstName": "Kellie",
"lastName": "Hoeger",
"email": "[email protected]",
"birthDate": "1956-06-01",
"birthCountry": "FR",
"residenceCountry": "IT",
"nationalities": [
"FR"
]
},
"status": "ACCEPTED",
"profiles": [
{
"id": "a7289388-c9ed-4d81-b493-c434a9914250",
"type": "PROJECT_HOLDER",
"status": {
"type": "ACCEPTED",
"subStatus": null
},
"wallets": [
{
"id": "599797b6-33d8-4d0a-bdf8-f811c2846727",
"internalId": 568068,
"type": "PAYMENT_ACCOUNT"
}
]
}
],
"information": {
"firstName": "Kellie",
"lastName": "Hoeger",
"birthDate": "1956-06-01T00:00:00.000Z",
"birthCity": "Lake Vern",
"birthCountry": "FR",
"nationalities": [
"FR"
],
"email": "[email protected]",
"phone": "+33675869559",
"city": "South Leslie",
"country": "IT",
"street": "44450 Quigley Underpass",
"streetComplementaryInfo": "bis",
"postalCode": "101",
"pep": {
"startDate": "2025-03-03T00:00:00.000Z",
"endDate": "2025-04-30T00:00:00.000Z",
"position": "MILITARY_LEADER"
},
"legalCapacity": {
"type": "OF_CAPACITY"
},
"professionalSituation": {
"activity": "69"
},
"financialSituation": {
"annualRevenue": "FIRST_TIER",
"estimatedWealth": "FIRST_TIER",
"isIFITax": true
},
"projects": [
{
"projectType": "FAREWELL",
"beneficiaryFirstName": "Laurel",
"beneficiaryLastName": "Sanford",
"beneficiaryBirthDate": "1951-01-09"
}
]
},
"type": "INDIVIDUAL",
"documents": [
{
"status": "VALIDATION_NOT_REQUIRED",
"type": "ONBOARDING_QUESTIONNAIRE",
"name": "403b2929-0451-4ce3-96bc-a3cdd439875a.pdf",
"downloadUrl": "https://account.dev.lemonway.com/accounts/f9137a42-20ca-40b0-8492-07b4eb45907b/documents/403b2929-0451-4ce3-96bc-a3cdd439875a.pdf"
},
{
"status": "PENDING_VERIFICATION",
"type": "PASSPORT",
"name": "feb9a94a-317b-4530-bdb8-8ac6363ee291.pdf",
"downloadUrl": "https://account.dev.lemonway.com/accounts/f9137a42-20ca-40b0-8492-07b4eb45907b/documents/feb9a94a-317b-4530-bdb8-8ac6363ee291.pdf"
},
{
"status": "VALIDATION_NOT_REQUIRED",
"type": "APPLICATION_FORM",
"name": "fb52b3e2-44cd-4187-8790-134347ba44d8.pdf",
"downloadUrl": "https://account.dev.lemonway.com/accounts/f9137a42-20ca-40b0-8492-07b4eb45907b/documents/fb52b3e2-44cd-4187-8790-134347ba44d8.pdf"
},
{
"status": "VALIDATION_NOT_REQUIRED",
"type": "SIGNED_DOCUMENT",
"name": "28e5b59b-51ec-4e08-963b-1d4a9f2285aa.pdf",
"downloadUrl": "https://account.dev.lemonway.com/accounts/f9137a42-20ca-40b0-8492-07b4eb45907b/documents/28e5b59b-51ec-4e08-963b-1d4a9f2285aa.pdf"
},
{
"status": "VALIDATION_NOT_REQUIRED",
"type": "MOTION_CAPTURE",
"name": "2e83dcf1-7698-472c-bac5-0bdfe182f254.pdf",
"downloadUrl": "https://account.dev.lemonway.com/accounts/f9137a42-20ca-40b0-8492-07b4eb45907b/documents/2e83dcf1-7698-472c-bac5-0bdfe182f254.pdf"
}
],
"createdAt": "2025-05-07T16:16:53.879Z"
}
Note
When account details are retrieved using GET /accounts/{:id}, only the basic information submitted during account creation (POST /accounts) is returned if the end-user is still in the onboarding process. The full data set, including any submitted documents, becomes accessible once the onboarding is complete—meaning the account status is either ACCEPTED or DENIED.
5. Get Documents
Description: This endpoint allows you to retrieve a document that was uploaded for a given account, using the account's UUID and a document name or logical identifier.Retrieve a previously uploaded document for a specific account. Only valid if a user has been fully Onboarded and accepted.
Path Parameters:
Name | Type | Format | Required | Description |
---|---|---|---|---|
accountId | string | uuid | Yes | The UUID of the account. |
documentName | string | — | Yes | The name or logical identifier of the document (e.g., DocumentType ). |
Endpoint: GET /accounts/{accountid}/documents/{documentName}
Resource: documents
5.1 HTTPs Responses:
Status Code | Description | Content-Type |
---|---|---|
200 | Document retrieved successfully | application/octet-stream |
400 | Invalid parameters | — |
401 | Unauthorized (missing or invalid API key or JWT token) | — |
403 | Forbidden | — |
404 | Document not found | — |
500 | Internal server error | — |
6. Upload Documents
Endpoint: POST /legal-entity-onboarding/{onboardingId}/document
Resource: legal-entity-onboarding
Security:
Scheme Name | Type | Location | Description |
---|---|---|---|
bearerAuth | HTTP | Header | Bearer token (JWT format required) |
Description: This endpoint allows uploading a document associated with a legal entity currently being onboarded.
Path Parameter:
Name | Type | Format | Required | Description |
---|---|---|---|---|
onboardingId | string | uuid | Yes | UUID of the onboarding entity |
Request Body (multipart/form-data)
Required Fields: type
, file
, accountId
Field | Type | Format | Description |
---|---|---|---|
type | string | — | Type of document to upload. See below. |
file | string | binary | The file to be uploaded. |
accountId | string | uuid | UUID of the account related to the document |
Document Types (type
enum values)
type
enum values)APPLICATION_FORM
ARTICLES_OF_ASSOCIATION
BOARD_MEMBERS_INFORMATION
BROCHURE
COMPANY_REGISTRY
DRIVING_LICENSE
EVIDENCE_FILE
FAMILY_DOCUMENT
LEGAL_CAPACITY_DOCUMENT
LEGAL_REPRESENTATIVE_DOCUMENT
MOTION_CAPTURE
NATIONAL_ID_CARD
OFFICIAL_NOTICE
OTHER
PASSPORT
PROOF_OF_ADDRESS
PROOF_OF_BANK_INFORMATION
PUBLICATION_EXCERPT
RESIDENCE_PERMIT
SHAREHOLDING_STRUCTURE_DOCUMENTATION
SIGNED_DOCUMENT
TAX_NOTICE
UBO_DOCUMENT
6.1 Responses
Status Code | Description | Content-Type |
---|---|---|
200 | Document uploaded successfully. Returns documentId and status . | application/json |
400 | Invalid request (missing parameters or invalid file) | — |
401 | Unauthorised (missing or invalid authentication token) | — |
404 | Onboarding or account not found | — |
500 | Internal server error | — |
Example Response (200 OK
)
200 OK
){
"documentId": "a1b2c3d4-e5f6-7890-ab12-cd34ef56gh78",
"status": "SUCCESS"
}