Key Endpoints
1. Create an Individual Account
2. Trigger an Onboarding (if required)
3. Resume an in-process Onboarding
4. Manage Onboarding
5. Get Documents
Endpoints for Online Onboarding for individuals
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 /accounts/individual | Provision a new individual account. |
| Trigger Onboarding | POST /onboardings/individual | If the account’s profile status is awaiting_information, start the onboarding flow. |
| Resume Onboarding | GET /onboardings/{onboardingId}/resume | Resume a previously-started, in-progress onboarding. |
| List All Accounts | GET /accounts | Retrieve a list of all individual (and/or corporate) accounts. |
| Retrieve Specific Account | GET /accounts/{id} | Fetch details for a single account by its unique ID. |
| Get Documents | GET /documents/{id} | Retrieve a list of all individual (and/or corporate) documents. |
1. Create an individual Account
Description: Create a new Individual Account
Request Body: An account object containing an individual field with the individuals details.
Endpoint: POST /accounts/individual
Resource: account (subtype: individual)
1.1 Payload
When you submit the following example JSON payload, the API will:
- Validates you’ve provided all required fields.
- Creates an account record of type “individual.”
- Associate a new wallet entry using the walletId.
- Returns a populated account object (including a server-assigned Id) so you can pass it into subsequent onboarding calls.
{
"individual": {
"firstName": "Jonathan",
"lastName": "Lamary",
"birthDate": "1973-06-01",
"email": "[email protected]",
"address": {
"country": "FR"
},
"birthCountry": "FR",
"nationalities": [
"FR",
"GB"
]
},
"profile": "PROJECT_HOLDER",
"walletId": "6768992",
}1.2 Parameters
| Attribute | Required | Example | Data Type | Description |
|---|---|---|---|---|
| firstName | Yes | Jonathan | string | The first name of the individual. |
| lastName | Yes | Lamary | string | The last name of the individual. |
| birthDate | Yes | 1973-06-01 | date | Date of birth (YYYY-MM-DD). |
| Yes | [email protected] | regex | The individual’s email address. | |
| birthCountry | Yes | FR | enum | ISO-2 code for country of birth. |
| nationalities | Yes | FR, GB | string[] | One or more ISO-2 country codes. |
| country | Yes | FR | string | ISO-2 code for country of residence. |
| profile | Yes | PROJECT_HOLDER | enum | User’s activity profile (only one). |
| walletId | Yes | f2470b35-4dd4-4fe1-bab2-f8c763ebcef5 | string | Unique identifier for the individual’s wallet. |
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 individual field with the person’s details.
Endpoint: POST /onboardings/individual
Resource: onboardings (subtype: individual)
To initiate the Online Onboarding process using the POST/onboardings/individual endpoint, you need to submit the same data you used for account creation, along with the accountId we provided. All other data are optional to initiate an Online Onboarding and will be collected directly from the end-user, ensuring compliance with KYC requirements without additional data input from your side.
Note
Some end-user personal information may be pre-filled when they open onboarding page for the first time, notably the name, email and contact details. We use the initial end-user data you sent us to inject into online onboarding page.
2.1 Payload
When you submit the following example JSON payload, the API will:
- Identifies the account and link this KYC process to it.
- All mandatory personal, contact, and address data for identity checks.
- Assesses AML/PEP risk via political exposure, financial profile, and source of funds.
- Verifies legal eligibility (age, capacity).
- Understands the user’s business intent (FAREWELL project) and downstream beneficiary.
- Redirects the user back to your specified redirectUrl once all steps succeed (or fail).
{
"accountId": "1256562",
"redirectUrl": "https://www.lemonway.com/",
"individual": {
"firstName": "Jonathan",
"lastName": "Lamary",
"birthDate": "1973-06-01",
"email": "[email protected]",
"birthCity": "Paris",
"birthCountry": "FR",
"phoneNumber": "+33675869559",
"nationalities": [
"FR"
],
"address": {
"street": "86017 Halle Loaf",
"city": "Aureliechester",
"postalCode": "311",
"province": "AO",
"country": "IT"
},
"politicalExposure": {
"status": "YES",
"position": "POLITICAL_LEADER",
"startDate": "1970-01-01"
},
"financialSituation": {
"annualRevenue": "FIRST_TIER",
"estimatedWealth": "FIRST_TIER",
"hasIFItax": true,
"taxCode": "HE23563769Y",
"originOfFunds": {
"sources": ["SAVINGS_ACCUMULATED_OVER_SEVERAL_YEARS"],
"other": "test"
}
},
"legalCapacity": {
"type": "LEGAL_AGE_AND_CAPACITY"
},
"professionalSituation": {
"activity": "69"
}
},
"project": {
"type": "FAREWELL",
"beneficiary": {
"firstName": "Jane",
"lastName": "Doe",
"birthDate": "1951-01-09"
}
}
}2.2 Parameters
Attribute | Required | Description | Data Type | Example |
|---|---|---|---|---|
firstName | Yes | Official first name that appears on the user's legal documents, such as a passport. | string | Jonathan (not John) |
lastName | Yes | Official last name that appears on the user's legal documents. | string | Doe |
otherName | No | Maiden name/married name, used name, pseudo. | string | Smith |
birthDate | Yes | Format: YYYY-MM-DD | date | 1980-07-10 |
birthCity | Yes | City of birth | string | Paris |
birthProvince | Yes (for individuals born in Italy) | From a provided list | ||
birthCountry | Yes | ISO-2 format | string | FR |
nationalities | Yes | ISO-2 format. Allows multiple nationalities. | string | FR, GB |
Yes | regex | |||
phoneNumber | Yes | Must include country code. | regex | +33689222211 |
street | Yes | string | 44 Rue de l'Abbaye | |
complementaryStreetInfo | No | string | Batiment A | |
city | Yes | string | Paris | |
postalCode | Yes | string | 75000 | |
province | Yes (for individuals living in Italy) | From a provided list | ||
residenceCountry | Yes | ISO-2 format | iso-alpha2 | FR |
taxCode | Yes (for individuals born or living in Italy) | Specific tax code format | string | MRTMTT91D08F205J |
status (Are you a politically exposed person?) | Yes | Politically exposed person status: enum { no, yes, close } | enum | Yes |
position | Yes (if status is "YES") | There are 9 identified positions and one option to state another position if it does not appear on the list. enum: { POLITICAL_LEADER, POLITICAL_REPRESENTATIVE, JUDICIAL_OFFICIAL, FINANCIAL_AUDITOR, BANK_EXECUTIVE, DIPLOMATIC_REPRESENTATIVE, MILITARY_LEADER, ADMINISTRATIVE_OFFICIAL, ORGANIZATIONAL_OFFICIAL, OTHER} | enum | POLITICAL_LEADER |
otherPosition | Yes (if position is "OTHER") | This option is selected if the person's job title does not appear in the provided list. The person must state their official position. | string | string |
startDate | Yes (if status is "YES" or "CLOSE") | Format: YYYY-MM-DD | date | 1980-07-10 |
endDate | Optional | Format: YYYY-MM-DD. If unknown, not required. | date | 2001-07-10 |
closeRelationship | Yes (if status is "CLOSE") | Options include: Child, Parent, Spouse (wife or husband) enum: { PARTNER, CHILD, PARENT } | enum | Child |
fullName | Yes (if status is "CLOSE") | Full legal name of the politically exposed person | string | Michael James |
professionalSituation | Yes | There are 3 broad categories, they are not an exhaustive list of professions, but offer the most common occupations:
| enum | 85.31 |
annualRevenue | Yes | This revenues are listed in a 6 tiers format. enum: { FIRST_TIER, SECOND_TIER, THIRD_TIER, FOURTH_TIER, FIFTH_TIER, SIXTH_TIER } { 0 - 10K> €10K € - 25K €
| enum | 0 - 10K € |
estimatedWealth | Yes | 7 tiers to select from. enum: { FIRST_TIER, SECOND_TIER, THIRD_TIER, FOURTH_TIER, FIFTH_TIER, SIXTH_TIER, SEVENTH_TIER } { 0 - 50K €> 50K € - 100K €
| enum | 0 - 50K € |
hasIFITax | Yes (only for French residents) | Boolean statement | boolean | true |
originOfFunds.sources | Yes (for investors only) | enum: {INCOME, REAL_ESTATE_PROPERTIES, SAVINGS_ACCUMULATED_OVER_SEVERAL_YEARS, DONATION_OR_INHERITANCE, SALE_OF_A_STOCK_PORTFOLIO, TRANSFER_OF_COMPANY_SHARES, WINNING_FROM_GAMES_OR_CONTESTS, SURRENDER_OF_A_CAPITALIZATION_CONTRACT_OR_LIFE_INSURANCE_POLICY, SALE_OF_MOVABLE_ASSETS_GOODWILL_INTELLECTUAL_PROPERTY_RIGHTS, SALE_OF_CURRENCY_GOLD_OR_CRYPTOCURRENCIES, FINANCIAL_INVESTMENTS, OTHER_OPERATIONS} | enum | Income (salary, etc.) |
originOfFunds.other | Required if origin is "OTHER_OPERATIONS" | Description of other origin of funds | string | |
type | Yes | The end-user is required to state their legal capacity. There are 4 options:
| enum | Protected adult |
protectionType | Yes (if type is "Protected adult") | Enum of protection types | enum | Family Guardianship |
otherProtectionType | Yes (if protection type is "OTHER") | Must specify other protection type | string |
2.3 Project-Specific Parameters (For Project Holder Profile)
Attribute | Required | Description | Data Type | Example |
|---|---|---|---|---|
projectType | Yes | The attribute allows the end-user to specify the type of the project they are collection funds for, there are 6 categories. enum: { WEDDING, FAREWELL, NEW_BORN, BIRTHDAY, CHARITY, OTHER } | enum | Wedding |
website | Yes | URL of the fund | string | |
description | Yes | Description of fund usage | string | |
weddingRelationType | Yes (if type is "Wedding") | enum: {BRIDE_GROOM, OTHER} | enum | Managing pot for groom and bride |
beneficiaryFirstName | Yes (if type is "Wedding") | The first name of the person who is receiving the funds, gift or service. | string | Matthew |
beneficiaryLastName | Yes (if type is "Wedding") | The last name of the person who is receiving the funds, gift or service. | string | Riley |
beneficiaryBirthDate | Yes (if type is "Wedding") | The date of birth of the person who is receiving the funds, gift or service | date | 1970-01-01 |
3. Resume an in-process 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 | — |