Online Onboarding: Legal Entity API Reference

Key Endpoints

  1. Create a Legal Entity Account
  2. Trigger an Onboarding
  3. Resume an Onboarding
  4. Manage an Onboarding
  5. Get Documents
  6. 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 /accounts/legal-entity

Provision a new legal entity account.

Trigger Onboarding

  • POST /onboardings/company
  • POST /onboardings/association
  • POST /onboardings/sole_trader

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 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 documents.

Upload Documents

POST /legal-entity-onboarding/{onboardingId}/document

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

FieldRequiredDescriptionTypeExample
nameYesLegal entity nameString"Example Company"
typeYesType of legal entityEnum"COMPANY"
registrationNumberYesRegistration number of the entityString"123456789"
registrationCountryYesCountry of registration (ISO 2-letter code)String"FR"
registrationDateYesDate of registration (YYYY-MM-DD)Date"2000-01-01"
firstNameYesRepresentative's first nameString"John"
lastNameYesRepresentative's last nameString"Doe"
birthDateYesRepresentative's birth date (YYYY-MM-DD)Date"1980-06-15"
emailYesRepresentative's email addressString"[email protected]"
address.countryYesRepresentative's country of residence (ISO code)String"FR"
birthCountryYesRepresentative's country of birth (ISO code)String"FR"
nationalitiesYesRepresentative's nationalities (ISO codes)Array["FR"]
profileYesProfile typeEnum"PROJECT_HOLDER"
walletIdYesUnique wallet identifierString"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

FieldRequiredDescriptionTypeExample
accountIdYesIdentifier of the created accountString"account-id"
redirectUrlYesURL to redirect after onboarding completionString"https://yourwebsite.com/callback"
legalEntityYesLegal entity detailsObjectSee above
legalRepresentativeYesRepresentative's detailsObjectSee 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:

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

6. Upload Documents

Endpoint: POST /legal-entity-onboarding/{onboardingId}/document
Resource: legal-entity-onboarding

Security:

Scheme NameTypeLocationDescription
bearerAuthHTTPHeaderBearer token (JWT format required)

Description: This endpoint allows uploading a document associated with a legal entity currently being onboarded.
Path Parameter:

NameTypeFormatRequiredDescription
onboardingIdstringuuidYesUUID of the onboarding entity

Request Body (multipart/form-data)

Required Fields: type, file, accountId

FieldTypeFormatDescription
typestringType of document to upload. See below.
filestringbinaryThe file to be uploaded.
accountIdstringuuidUUID of the account related to the document

Document Types (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 CodeDescriptionContent-Type
200Document uploaded successfully. Returns documentId and status.application/json
400Invalid request (missing parameters or invalid file)
401Unauthorised (missing or invalid authentication token)
404Onboarding or account not found
500Internal server error

Example Response (200 OK)

{
  "documentId": "a1b2c3d4-e5f6-7890-ab12-cd34ef56gh78",
  "status": "SUCCESS"
}