Online Onboarding: Legal Entity API Reference

Key Endpoints

Create a Legal Entity Account
Trigger an Onboarding
Resume an Onboarding
Manage an Onboarding
Get Documents
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 `/accounts/{accountid}/documents/{documentName}`	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

{
  "legalEntity": {
    "name": "Matt Claxton",
    "type": "ClaxtonBells",
    "registrationNumber": "126766Z",
    "registrationDate": "2025-08-11T08:10:18.405Z",
    "address": {
      "country": "FR"
    }
  },
  "legalRepresentative": {
    "firstName": "Diane",
    "lastName": "Bethney",
    "birthDate": "2025-08-11T08:10:18.405Z",
    "birthCountry": "UK",
    "nationalities": [
      "UK"
    ],
    "email": "[email protected]",
    "address": {
      "country": "UK"
    }
  },
  "profile": "INVESTOR",
   "activity": "CROWDEQUITY",//Required only if end user has multi-activities.
  "walletId": "1278782",
}

1.2 Response

{
  "id": "ff928147-d51e-4f22-b26c-d2c1a2sebd8d", <-- 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
}

1.3 Parameters

Field	Required	Description	Type	Example
`name`	Yes	Legal entity name	String	"Example Company"
`type`	Yes	Type of legal entity	Enum	"COMPANY"
`registrationNumber`	Yes	Registration number of the entity	String	"123456789"
`registrationCountry`	Yes	Country of registration (ISO 2-letter code)	String	"FR"
`registrationDate`	Yes	Date of registration (YYYY-MM-DD)	Date	"2000-01-01"
`firstName`	Yes	Representative's first name	String	"John"
`lastName`	Yes	Representative's last name	String	"Doe"
`birthDate`	Yes	Representative's birth date (YYYY-MM-DD)	Date	"1980-06-15"
`email`	Yes	Representative's email address	String	"[email protected]"
`address.country`	Yes	Representative's country of residence (ISO code)	String	"FR"
`birthCountry`	Yes	Representative's country of birth (ISO code)	String	"FR"
`nationalities`	Yes	Representative's nationalities (ISO codes)	Array	["FR"]
`profile`	Yes	Profile type	Enum	"PROJECT_HOLDER"
`walletId`	Yes	Unique wallet identifier	String	"unique-wallet-id"

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

{
  "accountId": "ACC123456789",
  "redirectUrl": "https://www.lemonway.com/",
  "legalEntity": {
    "name": "Globex Corporation",
    "brandName": "Alice brand",
    "registrationNumber": "50JoRegistrationDOUBLON",
    "registrationDate": "2014-09-25",
    "vatNumber": "X9F7G8H2K1",
    "website": "alice.biz",
    "taxCode": "MRTMTT91D08F205J",
    "legalForm": "SAS",
    "address": {
      "street": "42 Rue de l'Innovation",
      "city": "Lyon",
      "postalCode": "69007",
      "country": "FR",
      "province": "69"
    },
    "activity": {
      "NACEcode": "62.01Z",
      "ATECOcode": "62.01.00",
      "SAEcode": "6201",
      "description": "Delivering cutting-edge payment solutions.",
      "customersCountries": [
        "DE"
      ],
      "fundsDestinationCountries": {
        "sameFundCountryAsCompanyRegistration": false,
        "address": {
          "street": "88 Financial Street",
          "city": "Berlin",
          "postalCode": "10115",
          "country": "DE"
        }
      },
      "location": {
        "sameAddressAsCompanyRegistration": true,
        "address": {
          "street": "42 Rue de l'Innovation",
          "city": "Lyon",
          "postalCode": "69007",
          "country": "FR"
        }
      }
    },
    "project": {
      "description": "Expanding cross-border B2B payment infrastructure.",
      "website": "alice.biz"
    },
    "financialSituation": {
      "expectedActivityVolume": "FIRST-TIER",
      "currentTurnover": "THIRD-TIER",
      "previousTurnover": "FIRST_TIER",
      "financialAsset": "THIRD-THIER"
    },
    "shareholding": {
      "hasShareholders": true,
      "shareholders": [
        {
          "name": "Robert",
          "registrationCountry": "IT",
          "registrationNumber": "87234flux"
        }
      ]
    }
  },
  "legalRepresentative": {
    "firstName": "Johns",
    "lastName": "Aimar",
    "birthDate": "1985-04-12",
    "otherName": "Claire",
    "birthCity": "Milan",
    "birthCountry": "IT",
    "email": "[email protected]",
    "phoneNumber": "+33678787878",
    "nationalities": [
      "IT"
    ],
    "address": {
      "street": "10 Via Roma",
      "city": "Milan",
      "postalCode": "20121",
      "country": "IT"
    },
    "politicalExposure": {
      "position": "Municipal Councillor",
      "startDate": "2017-06-01",
      "endDate": "2022-05-31",
      "status": "Former"
    }
  }
}

2.2 Response

{
    "id": "aa8c6dc8-cc1e-4eda-aae1-365cc7b5228", <-- Lemonway autogenerated Onboarding identifier, string, uuid
    "url": "https://onboarding.sandbox.lemonway.com/d6795611-e957-457f-83fc-dd1c03775c08/welcome" <-- url to redirect the end-user to, string
}

2.3 Parameters

Field	Required	Description	Type	Example
`accountId`	Yes	Identifier of the created account	String	"account-id"
`redirectUrl`	Yes	URL to redirect after onboarding completion	String	"https://yourwebsite.com/callback"
`legalEntity`	Yes	Legal entity details	Object	See above
`legalRepresentative`	Yes	Representative's details	Object	See above

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

3.1 Response

{
    "url": "https://onboarding.sandbox.lemonway.com/e6795620-e927-452e-83fc-dd1c03985c08/welcome" <-- url to redirect the end-user to, string
}

4. Manage Onboarding

Description: Retrieve a list of all accounts associated with your organization.
Request Parameter:

Parameter	Description	Notes
$filter	A way to filter accounts based on certain criteria.	Supports a query syntax like `status eq 'active'` or `type eq 'corporate'`. Often used for narrowing down results in large datasets.
$size	Page size — number of accounts to return per request.	If unset, a default (like 50 or 100) is applied.
$orderBy	Which field to order the results by. Allowed values: `createdAt` (date account was created) or `type` (account type).	Works together with `$sort`.
$skipToken	A token for retrieving the next or previous page of results in pagination.	Often opaque; you just reuse the token provided in the previous response.
$skipDirection	Whether to paginate forwards (`next`) or backwards (`prev`).	Only relevant when `$skipToken` is provided.
$select	Restrict the returned fields to only those specified. Allowed fields: `createdAt`, `type`, `id`, `externalAccountId`, `status`, `profiles`.	Can reduce payload size and improve performance.
$sort	Sort order: ascending (`asc`) or descending (`desc`).	Works in conjunction with `$orderBy`.

Endpoint: GET /accounts
Resource: accounts

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

This would return the 50 most recently created active 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	—

6. Upload Documents

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

Security:

Scheme Name	Type	Location	Description
`bearerAuth`	HTTP	Header	Bearer token (JWT format required)

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

Name	Type	Format	Required	Description
`onboardingId`	string	uuid	Yes	UUID of the onboarding entity

Request Body (multipart/form-data)

Required Fields: type, file, accountId

Field	Type	Format	Description
`type`	string	—	Type of document to upload. See below.
`file`	string	binary	The file to be uploaded.
`accountId`	string	uuid	UUID of the account related to the document

Document Types (`type` enum values)

ARTICLES_OF_ASSOCIATION
BOARD_MEMBERS_INFORMATION
BROCHURE
COMPANY_REGISTRY
DRIVING_LICENSE
FAMILY_DOCUMENT
LEGAL_CAPACITY_DOCUMENT
LEGAL_REPRESENTATIVE_DOCUMENT
NATIONAL_IDENTITY_CARD
OFFICIAL_NOTICE
OTHER
PASSPORT
PROOF_OF_ADDRESS
PROOF_OF_BANK_INFORMATION
PUBLICATION_EXCERPT
RESIDENCE_PERMIT
SHAREHOLDING_STRUCTURE_DOCUMENTATION
TAX_NOTICE
UBO_DOCUMENT

6.1 Responses

Status Code	Description	Content-Type
`200`	Document uploaded successfully. Returns `documentId` and `status`.	`application/json`
`400`	Invalid request (missing parameters or invalid file)	—
`401`	Unauthorised (missing or invalid authentication token)	—
`404`	Onboarding or account not found	—
`500`	Internal server error	—

Example Response (`200 OK`)

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

Key Endpoints

Endpoints for Online Onboarding for Legal Entities

Note

1. Create a Legal Entity Account

1.1 Payload

1.2 Response

1.3 Parameters

2. Trigger an Onboarding

2.1 Payload

2.2 Response

2.3 Parameters

3. Resume Onboarding

3.1 Response

4. Manage Onboarding

4.1 Response

4.2 Response

Note

5. Get Documents

5.1 HTTPs Responses:

6. Upload Documents

Document Types (type enum values)

6.1 Responses

Example Response (200 OK)

Document Types (`type` enum values)

Example Response (`200 OK`)