Choose the business for your request
Use your institution’s API key withmerchants:read or merchants:write, as required by the endpoint. Managed-business access must be enabled for your account.
For onboarding requests, select your institution in X-Ledig-Business-Id and, if you send it, X-Ledig-Acting-Business-Id. Put the managed business’s ID in the URL:
canAct value is false. HMAC v1 or v2 can sign these requests because your institution remains selected.
When making payments for an onboarded business, select that business and use HMAC v2. See Authentication.
Create an application
CallGET /v1/managed-businesses to see the businesses you already manage. This list is not paginated.
To start an application, call POST /v1/managed-businesses/applications with an Idempotency-Key and the business name:
requestId, applicationId and businessId. Use businessId in the onboarding URLs below. Creating an application does not send an invitation; create a sharing link if you want the applicant to complete it.
Retrying with the same key and business name returns the original application request. Reusing that key with a different name returns 409.
Complete the application
These paths follow/v1/managed-businesses/{businessId}/onboarding:
Share each identity-verification session only with the person who must complete it. That person should complete their own identity and liveness checks.
When editing a section, first read its current answers. Send all answers you want to keep together with your changes:
PUT /{section} replaces the saved section, so omitted answers are removed. Saving a draft does not mark the section complete or submit the application.
Avoid overwriting another person’s edits
Your team and the applicant may edit the same application. UseIf-Match to make sure you are updating the version you last read:
- Read
data.updatedAtfromGET .../onboarding/sections. - Send that exact value, surrounded by double quotes, in
If-Matchwith your next change. - After a successful change, copy the returned
ETaginto the next request’sIf-Matchheader. - If a request returns
409for a missing or outdated revision, reload the application and compare the saved answers with your unsaved changes before retrying.
JSON.stringify(sectionList.data.updatedAt). For later writes, use response.headers.get("ETag") directly.
Include If-Match when saving or completing sections, adding or removing owners, registering or completing uploads, and submitting the application. If one step in a series fails, read the application again before resuming; earlier steps may already have succeeded.
Upload documents
Use the document requirements returned by the section’s options endpoint. Each upload has three steps:- Register the file. Call
POST .../onboarding/documentswith the currentIf-Match, the required document fields, itssizeBytesand a SHA-256 checksum calculated from the file. Savedata.document.id,data.uploadand the returnedETag. - Upload the file. PUT the file bytes to
data.upload.uploadUrlbefore it expires, including every returnedrequiredHeadersvalue. Do not add Ledig API authentication to this URL. In a browser, let the browser setContent-Length. - Confirm the upload. Call
POST .../onboarding/documents/{documentId}/completewith theETagfrom registration inIf-Match. Save the returned document result and use the newETagfor your next edit.
maxSizeBytes and allowedMimeTypes before uploading.
Use the filename, MIME type, byte count and checksum of the exact file you will upload. Do not reuse the fictional file metadata from an example for a different file.
If the file is damaged, unreadable or does not meet the upload requirements, use the returned correction message and replace it. If validation is temporarily unavailable, retry completion for the same document instead of uploading another copy.
Do not mark an interrupted upload as complete. If you lose a response, retain the document ID and check the application before retrying. Repeating completion with the current revision keeps the original document result.
A failed completion or submission may return x-onboarding-committed-revision. Use that header as your next If-Match value for that application, then follow the correction message. Preserve any unrelated unsaved answers when refreshing the application.
Submit and follow corrections
Once the required sections and documents are complete, callPOST .../onboarding/submit with the current If-Match.
After submission, read the returned application status and follow any required owner identity checks. For an individual beneficial owner who needs verification, call POST .../onboarding/owners/{ownerId}/verification to start or resume their session. This step requires a submitted application; it is not available for every shareholder. Each person must complete their own identity and liveness checks.
Read the application to follow its review status. If status is changes_requested, reviewReason explains what to correct. Update the requested sections or documents and submit again.
A successful upload or identity check is one step in onboarding. Wait for the business’s application outcome before treating it as approved.
Sharing links
A sharing link lets the applicant complete the application without creating a Ledig account. It gives access to the application only, not the business’s funds or dashboard.
Keep your institution selected for these requests. Links expire after seven days, and you can revoke them earlier. Replacing a link also ends access through the old link and its sessions. If
replaceSessionId is outdated, the request returns 409.
The URL is returned only when it is created and is not emailed automatically. Share it securely with the applicant. If you lose the creation response, read the current sharing status and replace the existing link.
Make requests for an onboarded business
When the business is active andcanAct is true, select its ID in X-Ledig-Business-Id and sign requests with HMAC v2 using your institution’s key. The requested service and permissions must also be available.
Each payment uses that business’s funds, limits and approved recipients. Managing a business does not combine its balances with your institution’s balances.