Skip to main content
Institutional accounts can onboard and manage other businesses through the API. Each managed business has its own balances, limits, recipients and transaction history. You can complete an application on the business’s behalf or share a link so its applicant can provide the information.

Choose the business for your request

Use your institution’s API key with merchants: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:
You can complete onboarding while the managed business’s 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

Call GET /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:
Save the returned 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. Use If-Match to make sure you are updating the version you last read:
  1. Read data.updatedAt from GET .../onboarding/sections.
  2. Send that exact value, surrounded by double quotes, in If-Match with your next change.
  3. After a successful change, copy the returned ETag into the next request’s If-Match header.
  4. If a request returns 409 for a missing or outdated revision, reload the application and compare the saved answers with your unsaved changes before retrying.
For the first write, build the header with 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:
  1. Register the file. Call POST .../onboarding/documents with the current If-Match, the required document fields, its sizeBytes and a SHA-256 checksum calculated from the file. Save data.document.id, data.upload and the returned ETag.
  2. Upload the file. PUT the file bytes to data.upload.uploadUrl before it expires, including every returned requiredHeaders value. Do not add Ledig API authentication to this URL. In a browser, let the browser set Content-Length.
  3. Confirm the upload. Call POST .../onboarding/documents/{documentId}/complete with the ETag from registration in If-Match. Save the returned document result and use the new ETag for your next edit.
PDF, JPEG and PNG files are supported, up to 50 MiB each. Check the returned 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.
Upload and verification URLs give access to private information. Share them only with the intended person, keep them out of logs and analytics, and use them before they expire.

Submit and follow corrections

Once the required sections and documents are complete, call POST .../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. 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.
Anyone with the sharing link can read, edit and submit the application. Send it only to the intended applicant and keep it out of logs and analytics.

Make requests for an onboarded business

When the business is active and canAct 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.