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.

OperationsEndpointsDescription
Create an AccountPOST /accounts/individualProvision a new individual account.
Trigger OnboardingPOST /onboardings/individualIf the account’s profile status is awaiting_information, start the onboarding flow.
Resume OnboardingGET /onboardings/{onboardingId}/resumeResume a previously-started, in-progress onboarding.
List All AccountsGET /accountsRetrieve a list of all individual (and/or corporate) accounts.
Retrieve Specific AccountGET /accounts/{id}Fetch details for a single account by its unique ID.
Get DocumentsGET /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

AttributeRequiredExampleData TypeDescription
firstNameYesJonathanstringThe first name of the individual.
lastNameYesLamarystringThe last name of the individual.
birthDateYes1973-06-01dateDate of birth (YYYY-MM-DD).
emailYes[email protected]regexThe individual’s email address.
birthCountryYesFRenumISO-2 code for country of birth.
nationalitiesYesFR, GBstring[]One or more ISO-2 country codes.
countryYesFRstringISO-2 code for country of residence.
profileYesPROJECT_HOLDER

Other options: DONOR, INVESTOR, LENDER, BUYER,
MERCHANT, CREDITOR, OPERATOR, CONTENT_EDITOR, OTHER_OPERATOR

enumUser’s activity profile (only one).
walletIdYesf2470b35-4dd4-4fe1-bab2-f8c763ebcef5stringUnique 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:

  1. Professional activity - example: teacher, IT manager
  2. Non-professional activity - example: student, unemployed
  3. 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:

NameTypeFormatRequiredDescription
accountIdstringuuidYesThe UUID of the account.
documentNamestringYesThe name or logical identifier of the document (e.g., DocumentType).

Endpoint: GET /accounts/{accountid}/documents/{documentName}
Resource: documents

5.1 HTTPs Responses:

Status CodeDescriptionContent-Type
200Document retrieved successfullyapplication/octet-stream
400Invalid parameters
401Unauthorized (missing or invalid API key or JWT token)
403Forbidden
404Document not found
500Internal server error