Copy of 🆕 Online Onboarding: Individual API Reference

Individual API Reference

📘

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.

👍

Important

As a reminder, the following uniqueness criteria must be respected when creating Accounts:

• Individuals: first name, last name, date of birth, country of birth
• Legal Entities: name, registration number (company only), registration country, registration date
• Legal Representatives: same rules as for individuals

Please ensure that real and accurate data is always provided. Random or placeholder data must not be used, even if the information might later be updated during online onboarding.

1. Create an individual Account

1.1 Parameters for Creating an Account

1.2 Payload and Response

👍

Information

In the Response a unique Id is created. This Id corresponds to the accountId field in the endpoint POST /onboardings/individual.

{
    "individual": {
        "firstName": "Jonathan",
        "lastName": "Lamary",
        "birthDate": "1973-06-01",
        "email": "[email protected]",
        "address": { "country": "FR" },
        "birthCountry": "FR",
        "nationalities": ["FR", "GB"]
    },
    "profile": "DONOR",
    "walletId": "6768992"
}

{
  "id": "ee928147-d51e-4f22-a26c-d2c2a2sebd8d", <-- Lemonway autogenerated account identifier, string, uuid
  "status": "CREATED", <-- "global" status for the account, string
  "profileStatus": "AWAITING_INFORMATION" <-- profile showing the progress of the onboarding process, string
}

Expected Result - 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.

2. Trigger an Onboarding

📘

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 Parameters for Triggering an Onboarding

{
  "accountId": "b3b5a4e0-6a2e-4a0e-9e4d-4c6b0c5f7a21",
  "redirectUrl": "https://www.lemonway.com/",
  "individual": {
    "firstName": "Giulia",
    "lastName": "Romanelli",
    "birthDate": "1990-05-14",
    "email": "[email protected]",
    "birthCity": "Torino",
    "birthCountry": "IT",
    "phoneNumber": "+33675869559",
    "nationalities": [
      "IT"
    ],
    "taxCode": "235 6376", // Italian Residents only
    "address": {
      "street": "Via Roma 12",
      "complementaryStreetInfo": "bis",
      "city": "Torino",
      "postalCode": "10121",
      "country": "IT",
      "province": "AL"
    },
    "politicalExposure": {
      "position": "OTHER",
      "otherPosition": "Member of Parliament",
      "startDate": "2015-01-01",
      "endDate": "2017-12-31",
      "status": "YES"
    },
    "financialSituation": {
      "annualRevenue": "50K € - 75K €",
      "estimatedWealth": "100K € - 150K €",
      "hasIFItax": true // French Residents only
    },
    "legalCapacity": { "type": "EmancipatedAdult" },
    "professionalSituation": { "activity": "69" }
  },
  "project": {
    "type": "Crowdfunding",
    "beneficiary": {
      "firstName": "Luca",
      "lastName": "Rossi",
      "birthDate": "1992-09-21"
    }
  }
}

2.2 Parameters for Project Specific (Project Holder Profile)

"project": {
  "type": "WEDDING",
  "weddingRelation": "BRIDE_GROOM",
  "weddingPartnerFirstName": "Hector",
  "weddingPartnerLastName": "EMPEREUR",
  "weddingPartnerBirthDate": "1996-01-09"
}

"project": {
  "type": "WEDDING",
  "weddingRelation": "OTHER",
  "beneficiary": {
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1951-01-09"
  }
}

"project": {
  "type": "FAREWELL",
  "beneficiary": {
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1951-01-09"
  }
}
// Replace "FAREWELL" with "BIRTHDAY" or "NEW_BORN" as needed

"project": {
  "type": "CHARITY",
  "description": "lorem ipsum",
  "website": "loremipsum.com"
}
// For "OTHER", keep "type": "OTHER" and include relevant description/website if applicable

2.3 Parameters for Visa Applicant Account

{
  "financialSupport": {
    "visaApplicantRole": "STUDENT",
    "isPayer": false,
    "payerRelationship": {
      "link": "MOTHER_FATHER"
    }
  }
}

{
  "financialSupport": {
    "visaApplicantRole": "JOB_SEEKER",
    "isPayer": true,
    "financialSituation": {
      "annualRevenue": "FIRST_TIER",
      "estimatedWealth": "FIRST_TIER",
      "originOfFunds": {
        "sources": [
          "SAVINGS_ACCUMULATED_OVER_SEVERAL_YEARS"
        ],
        "other": "test"
      }
    }
  }
}

{
  "individual": {
    "firstName": "Claire",
    "lastName": "Dubois",
    "birthDate": "1995-06-01",
    "email": "[email protected]",
    "address": {
      "country": "FR"
    },
    "birthCountry": "FR",
    "nationalities": [
      "FR"
    ]
  },
  "activity": "VISA_ACCOUNT_APPLICATION",
  "profile": "PAYER",
  "walletId": "d5a3b2f1-78a4-4c7f-9e9b-98f0e4a0fef3"
}

👍

Information

For the Payer profile (isPayer), only a POST /accounts/individual is necessary. A Payer is a USER profile that does not require an Online Onboarding.

2.4 Responses

👍

Information

In the Response a unique id is created. This Id corresponds to the onboardingId required in the path pareameters of the endpoint GET /onboardings/{onboardingId}/resume. This required if a user decides to not complete the onboarding in one session.

Expected Result for all use cases - When you submit the following example JSON payload, the API will:

• Identify the account and link this KYC process to it.
• All mandatory personal, contact, and address data for identity checks.
• Assess AML/PEP risk via political exposure, financial profile, and source of funds.
• Verify legal eligibility (age, capacity).
• Understand the user’s business intent (FAREWELL project) and downstream beneficiary.
• Redirect the user back to your specified redirectUrl once all steps succeed (or fail).

{
  "id": "cc8c6dc8-cb1e-4edc-aae1-3652cc7b5228", <-- Lemonway autogenerated Onboarding identifier, string, uuid
  "url": "https://onboarding.sandbox.lemonway.com/d6795600-e957-457f-83fc-dd1c03775c08/welcome" <-- url to redirect the end-user to, string
}

📘

Note

The response will be displayed in the same format as a the standard response for these specific payloads.

3. Resume an in-process Onboarding

3.1 Response

{
  "url": "https://onboarding.sandbox.lemonway.com/e6795620-e917-452f-83fc-dd1c03775c08/welcome"  // url to redirect the end-user to, string
}

4. Manage Onboarding - Active Accounts

This example returns 50 of the most recently created active accounts:

GET /accounts?$filter=status eq 'active'&$size=50&$orderBy=createdAt&$sort=desc

4.1 Parameters to view all active Accounts

4.2 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": ""
}

5. Manage Onboarding - Retrieve Account by id

5.1 Response

{
  "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"
}

👍

Information

When you call POST /accounts/individual, the API returns a unique id for the new account in the response. Use this id in place of {id} in later requests (e.g., /accounts/{id}).

👍

Information

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.

6. Get Documents

6.1 Parameters to retreieve documents uploaded

Document Types (type enum values)

6.2 HTTPs Responses: