> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ledig.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed businesses

> Onboard businesses and make payments on their behalf.

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:

```http theme={null}
GET /v1/managed-businesses/{businessId}/onboarding
```

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](https://docs.ledig.io/auth/authentication.md#managed-business-delegation).

## 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:

```http theme={null}
POST /v1/managed-businesses/applications
Idempotency-Key: YOUR_IDEMPOTENCY_KEY
Content-Type: application/json
```

```json theme={null}
{
  "businessName": "Example Trading Ltd"
}
```

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](#sharing-links) 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`:

| Method and path | Purpose |
| - | - |
| `GET /` | Read the application status, progress and any corrections needed. |
| `GET /sections` | Read sections, saved answers and the current `updatedAt` value. |
| `GET /{section}` | Read one section. |
| `GET /{section}/options` | Get form choices and required documents. |
| `PUT /{section}` | Replace the section's saved answers in the endpoint's `{ "data": ... }` shape. |
| `POST /{section}/complete` | Validate a section and mark it complete. |
| `POST /owners` | Add an owner or related person. |
| `DELETE /owners/{ownerId}` | Remove a related person. |
| `POST /submit` | Submit the completed application for review. |
| `POST /owners/{ownerId}/verification` | Start or resume a required owner's identity verification after submission. |

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.

> [!WARNING]
>
> 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.

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

| Action | Path after `/onboarding` |
| - | - |
| Check the sharing link's status | `GET /share` |
| Create a link | `POST /share` with `{}` |
| Replace a link | `POST /share` with `replaceSessionId` from the latest status response |
| Revoke a link | `DELETE /share/{sessionId}` |

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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.