Online Onboarding: Individual API Reference

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 `/accounts/{accountid}/documents/{documentName}`	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).
email	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` Other options: DONOR, INVESTOR, LENDER, BUYER, MERCHANT, CREDITOR, OPERATOR, CONTENT_EDITOR, OTHER_OPERATOR	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		List of BIRTH PROVINCE
birthCountry	Yes	ISO-2 format	string	FR
nationalities	Yes	ISO-2 format. Allows multiple nationalities.	string	FR, GB
email	Yes		regex	[email protected]
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		List of RESIDENCE PROVINCES
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 of relationships: { 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: Professional activity - example: teacher, IT manager Non-professional activity - example: student, unemployed RetiredComplete list of PCS2020 Codes we use can be provided by your implementation manager if you want to collect this information on your site.	enum	85.31
annualRevenue	Yes	This revenues are listed in a 6 tiers format. Note: All listings are in Euro. enum: { FIRST_TIER, SECOND_TIER, THIRD_TIER, FOURTH_TIER, FIFTH_TIER, SIXTH_TIER } { 0 - 10K> €10K € - 25K € 25K € - 50K € 50K € - 75K € 75K € - 100K € 100 000 € }	enum	0 - 10K €
estimatedWealth	Yes	7 tiers to select from. Note: All listings are in Euro. enum: { FIRST_TIER, SECOND_TIER, THIRD_TIER, FOURTH_TIER, FIFTH_TIER, SIXTH_TIER, SEVENTH_TIER } { 0 - 50K €> 50K € - 100K € 100K € - 150K € 150K €- 200K € 200K - 500K € 500K € - 1M € 1M € }	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: For adults: Of legal age and capacity Protected adult For minors: Non emancipated minor Emancipated minorenum: {LEGAL_AGE_AND_CAPACITY, PROTECTED_ADULT, MINOR_EMANCIPATED, MINOR_NOT_EMANCIPATED}	enum	Protected adult
protectionType	Yes (if type is "Protected adult")	Enum of protection types enum: { SAFEGUARDING_OF_JUSTICE, CURATORSHIP, GUARDIANSHIP, OTHER }	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	www.shellywedding.co
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	—