> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/onboarding.md).

# Onboarding

The Onboarding APIs support programmatic merchant application creation, hosted signer completion, status tracking, attachment handling, and onboarding event handling.

Use this section when you want to create applications from your own product, prefill merchant data, send the signer through Bead's hosted onboarding experience, track progress in your own systems, or automate follow-up and operational workflows.

If you only need to onboard a small number of merchants manually, portal-based onboarding may be the simpler path.

#### What the onboarding APIs support

With the onboarding APIs, you can:

* save a merchant application as a Draft with whatever data you have, then submit it when you are ready
* create merchant onboarding applications from your own system
* choose between a full application flow and a short application flow
* prefill merchant, stakeholder, banking, and fee information when needed
* control whether the application is submitted immediately or created in Draft status
* upload supporting documents while the application is a Draft or prepared
* review and correct a prepared application, then send it to the applicant
* route the signer through Bead's hosted onboarding and signing experience
* track application progress and current status
* list and filter applications across a partner hierarchy
* email the applicant their invitation again
* subscribe to webhook events for application lifecycle updates

#### Recommended: Draft and Submit

The recommended starting point for every new integration is Draft and Submit. Collect what you can, send it to the Draft endpoint, attach files if you have them, and submit when the application is ready.

```http
POST /merchant-onboarding/applications/drafts
```

The same endpoint serves a full merchant profile or a minimal one. Only `partnerId` and `merchantName` are required, and everything else can be added later with `PUT /merchant-onboarding/applications/drafts/{applicationId}`. Nothing reaches the applicant until you submit the application and it is sent. Submit with:

```http
POST /merchant-onboarding/applications/{applicationId}/submit
```

After submit, the application moves to `preparing` while Bead gathers business information, then waits in `prepared` for someone to send it to the applicant with `POST /merchant-onboarding/{applicationId}/send-to-applicant`. See [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md).

In the Draft and Submit flow:

* the request body wraps all merchant fields in `merchantData`
* the signer is identified within `merchantData.stakeholders` with `isApplicationSigner: true`
* format and completeness checks run at submit, so partial data can be saved without errors
* attachments can be uploaded while the application is a Draft or prepared
* a Draft that is no longer needed can be discarded with `DELETE /merchant-onboarding/applications/drafts/{applicationId}`

See [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md) for the full flow, field guidance, and a complete sample.

#### Alternative single call patterns

The two original create endpoints remain available and fully supported. Use them if you already integrated with either one, or if you prefer a single call that creates and submits the application. There are two patterns.

**Full application**

Endpoint:

```http
POST /merchant-onboarding/applications
```

The full application flow is best when your platform already has most of the merchant's onboarding data and you want to prefill as much of the application as possible before the signer reviews it.

In the full application flow:

* the request body is submitted in `merchantData`
* merchant identity, business details, stakeholder data, banking details, fee information, and `cryptoEnvironment` are included in `merchantData`
* the signer is identified within `merchantData.stakeholders`
* the stakeholder who should sign is marked with `isApplicationSigner: true`
* `submitImmediately` controls whether the application is submitted immediately or created in Draft status
* `skipPartnerReview` controls whether Bead sends the application to the applicant automatically when it reaches `prepared`

This flow is a strong fit when you want tighter control over the submitted payload and want the signer to mainly review, confirm, and sign.

**Short application**

Endpoint:

```http
POST /merchant-onboarding/applications-short
```

The short application flow is best when you want a lighter entry point and prefer the hosted onboarding experience to collect most of the remaining merchant information.

A short application includes:

* `merchantName`
* `partnerId`
* `partnerMid`
* `signerFirstName`
* `signerLastName`
* `signerEmail`
* `feeInformation`
* `cryptoEnvironment`
* `submitImmediately`
* `skipPartnerReview` (optional)

This flow is a strong fit when you want to minimize onboarding data collection in your own system and get the signer into the hosted flow quickly.

#### Shared onboarding inputs

All submission patterns rely on these key inputs:

* signer details
* fee information
* `cryptoEnvironment`

The two single call patterns also accept `submitImmediately`. It is not accepted on Draft requests, where you control timing by calling submit.

For Draft and full applications, signer details are represented through the stakeholder marked with `isApplicationSigner: true`.

For short applications, signer details are sent as top level fields.

`feeInformation` should be aligned to the merchant's agreed commercial setup before the application is submitted.

`cryptoEnvironment` should match the environment you are working in, such as `sandbox` for Sandbox testing and `production` for Production onboarding.

For `POST /merchant-onboarding/applications` and `POST /merchant-onboarding/applications-short`, `submitImmediately` controls whether the application is submitted when it is created or created in Draft status.

| Value   | Behavior                                                                                          |
| ------- | ------------------------------------------------------------------------------------------------- |
| omitted | Bead preserves the existing default behavior and submits the application immediately.             |
| `true`  | Bead creates the application and submits it. It moves to `preparing`, then `prepared`.            |
| `false` | Bead creates the application in Draft status so attachments can be uploaded before you submit it. |

Use `submitImmediately: true` for the simplest single call flow.

Use `submitImmediately: false` when you need to upload supporting documents before the application is submitted. New integrations should prefer `POST /merchant-onboarding/applications/drafts` for this purpose.

An application that is submitted waits in `prepared` until it is sent to the applicant. Set `skipPartnerReview` to `true` to have Bead send it automatically, or call `POST /merchant-onboarding/{applicationId}/send-to-applicant`. When you omit `skipPartnerReview`, Bead applies the default for the environment.

#### High-level onboarding flow

A typical onboarding workflow depends on whether you use Draft and Submit or one of the single call patterns.

**Draft and Submit flow (recommended)**

1. Create the Draft with the data you have.

```http
POST /merchant-onboarding/applications/drafts
```

```json
{
  "merchantData": {
    "partnerId": "partner_123",
    "merchantName": "Northwind Coffee Roasters"
  }
}
```

2. Optionally update the Draft as you collect more data.

```http
PUT /merchant-onboarding/applications/drafts/{applicationId}
```

3. Optionally upload attachments while the application is in Draft status.

```http
POST /merchant-onboarding/applications/{applicationId}/attachments
```

4. Optionally list or download attachments to verify the package.

```http
GET /merchant-onboarding/applications/{applicationId}/attachments
GET /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}
```

5. Submit the Draft.

```http
POST /merchant-onboarding/applications/{applicationId}/submit
```

6. Wait for the application to reach `prepared`.

After submit, the application moves to `preparing` while Bead gathers business information, then to `prepared`. It waits in `prepared` until someone sends it. You can still correct the application and add attachments while it is `prepared`.

7. Review, correct if needed, and send to the applicant.

```http
POST /merchant-onboarding/{applicationId}/send-to-applicant
```

The applicant is emailed a link to finish and sign, and the application moves to `signing`. An application created with skip partner review is sent automatically at `prepared`, so you do not call send for it.

8. If the applicant needs the email again, resend it.

```http
POST /merchant-onboarding/{applicationId}/resend-to-applicant
```

Resend works only while the application is in `signing`.

9. Track progress.

Track application progress by polling Get Status, using webhooks, or both.

10. Continue through review and boarding.

After signature, the application moves through review and downstream boarding.

A typical status path may look like:

```
draft → preparing → prepared → signing → signed → reviewing → reviewed → boarding → boarded
```

**Single call flow with immediate submit**

Use this flow if you already integrated with the create endpoints and attachments are not required before submit.

1. Create the application.

```http
POST /merchant-onboarding/applications
POST /merchant-onboarding/applications-short
```

Use `submitImmediately: true`, or omit the field if you want the default immediate submit behavior. The response returns `applicationId`.

2. Bead prepares the application.

The application moves to `preparing` while Bead gathers business information, then to `prepared`.

3. The application is sent to the signer.

With `skipPartnerReview: true`, Bead sends it automatically when it reaches `prepared`. Otherwise, call `POST /merchant-onboarding/{applicationId}/send-to-applicant`. The signer receives the hosted onboarding and signing experience using the signer details provided in the request.

4. The signer reviews and signs.

In the full application flow, the signer reviews a more complete prefilled application.

In the short application flow, the signer supplies more of the required business information directly in the hosted experience.

5. Track progress.

Track application progress by polling Get Status, using webhooks, or both.

6. Continue through review and boarding.

After signature, the application moves through review and downstream boarding.

A typical status path may look like:

```
preparing → prepared → signing → signed → reviewing → reviewed → boarding → boarded
```

**Single call flow with Draft and attachments**

If you created the application with `POST /merchant-onboarding/applications` and `submitImmediately: false`, the flow is the same as Draft and Submit from the attachment step onward.

1. Create the application with `submitImmediately: false`.

```json
{
  "submitImmediately": false,
  "merchantData": {
    "...": "..."
  }
}
```

2. Upload attachments while the application is in Draft status.

```http
POST /merchant-onboarding/applications/{applicationId}/attachments
```

3. Submit the Draft application.

```http
POST /merchant-onboarding/applications/{applicationId}/submit
```

4. Send the prepared application to the applicant, then track progress the same way as the other flows.

```http
POST /merchant-onboarding/{applicationId}/send-to-applicant
```

#### Application identifiers

All create endpoints return a response that includes `applicationId`. The submit command returns:

* `applicationId`
* `envelopeId`

Store `applicationId` so you can track status, reconcile activity, update or discard Drafts, submit Draft applications, send or resend applications to the applicant, and support follow-up workflows later. Every Bead onboarding endpoint takes `applicationId`.

`envelopeId` is an internal signing reference. You do not need it for any Bead API call, and you can ignore it unless Bead support asks for it.

#### Core onboarding endpoints

The core merchant onboarding endpoints are:

```http
POST /merchant-onboarding/applications/drafts
PUT /merchant-onboarding/applications/drafts/{applicationId}
DELETE /merchant-onboarding/applications/drafts/{applicationId}
POST /merchant-onboarding/applications
POST /merchant-onboarding/applications-short
GET /merchant-onboarding/applications/{applicationId}
GET /Partners/{id}/applications
POST /merchant-onboarding/applications/{applicationId}/submit
POST /merchant-onboarding/{applicationId}/send-to-applicant
POST /merchant-onboarding/{applicationId}/resend-to-applicant
GET /merchant-onboarding/applications/{applicationId}/history
POST /merchant-onboarding/applications/{applicationId}/attachments
GET /merchant-onboarding/applications/{applicationId}/attachments
GET /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}
DELETE /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}
POST /merchant-onboarding/{applicationId}/cancel
POST /merchant-onboarding/{partnerId}/webhook
PUT /merchant-onboarding/{partnerId}/webhook
DELETE /merchant-onboarding/{partnerId}/webhook
```

{% hint style="warning" %}
**Deprecated:** `GET /merchant-onboarding/applications` is deprecated. Use `GET /Partners/{id}/applications` instead, see [List Applications](https://developers.bead.xyz/onboarding/list-applications.md).
{% endhint %}

#### Create, Submit, Discard, Send, and Resend

These commands are related but serve different purposes.

| Action                        | Endpoint                                                                                                                   | Use when                                                                                                                                         |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Create Draft (recommended)    | `POST /merchant-onboarding/applications/drafts`                                                                            | You want to save whatever merchant data you have and submit the application later.                                                               |
| Update Draft                  | `PUT /merchant-onboarding/applications/drafts/{applicationId}`                                                             | The application is in Draft or `prepared` status and you have more or corrected data. This replaces the stored data.                             |
| Discard Draft                 | `DELETE /merchant-onboarding/applications/drafts/{applicationId}`                                                          | The application is in Draft status and is no longer needed. This permanently deletes it.                                                         |
| Submit Draft                  | `POST /merchant-onboarding/applications/{applicationId}/submit`                                                            | The application is in Draft status and is ready to move forward. It then moves to `preparing` and `prepared`.                                    |
| Send to applicant             | `POST /merchant-onboarding/{applicationId}/send-to-applicant`                                                              | The application is in `prepared`. This is the first send, and the application moves to `signing`.                                                |
| Resend to applicant           | `POST /merchant-onboarding/{applicationId}/resend-to-applicant`                                                            | The application is in `signing` and the applicant needs the invitation emailed again with the same link.                                         |
| Create and immediately submit | `POST /merchant-onboarding/applications` or `POST /merchant-onboarding/applications-short` with `submitImmediately: true`  | You want Bead to create and submit the application in a single call. It then waits in `prepared` to be sent, unless skip partner review applies. |
| Create Draft (single call)    | `POST /merchant-onboarding/applications` or `POST /merchant-onboarding/applications-short` with `submitImmediately: false` | You use the original create endpoints and need the application to stay in Draft status.                                                          |

Send works only in `prepared` and resend works only in `signing`. Any other status returns `400` with the current status.

#### Relationship to other areas

**Onboarding and Entity Management**

Onboarding captures and reviews merchant data.

After approval and downstream boarding, Entity Management is used to create or maintain merchants, locations, terminals, and related entities based on the approved onboarding outcome.

**Onboarding and Payments, Reporting, and Settlement**

Payments use the merchant, location, and terminal entities that are available after onboarding and downstream setup are complete.

Reporting and Settlement use those same entities for history, reconciliation, and funding visibility.

A common implementation sequence is:

1. Implement Onboarding
2. Implement Entity Management
3. Implement Payments
4. Implement Reporting and Settlement

#### Getting started

Before you build your onboarding integration:

1. Obtain your onboarding API key.
2. Start with Draft and Submit. Review Draft and Submit (Recommended) for the flow and a complete sample.
3. Decide which merchant data you will send at Draft creation and which you will add later with an update.
4. Review Fee Configuration for Onboarding Applications so your submitted fees match the merchant's commercial agreement.
5. If you have supporting documents, review Application Attachments and upload them while the application is a Draft or prepared.
6. Review the onboarding request and response models in the Reference Guide.
7. Decide how your system will track status changes, whether by polling, webhooks, or both.
8. Make sure your integration sets `cryptoEnvironment` correctly for the target environment.
9. Test your first end-to-end workflow in Sandbox.

If you already integrated with `POST /merchant-onboarding/applications` or `POST /merchant-onboarding/applications-short`, you can keep using them. Review Submit Application for those flows.

#### Related pages

[**Draft and Submit (Recommended)**](https://developers.bead.xyz/onboarding/draft-and-submit.md)

The recommended onboarding pattern. Save a Draft with the data you have, attach files, update as needed, and submit when ready.

Includes the endpoint set, strict field names, what submit checks, discard behavior, and full and minimal samples.

[**Submit Application**](https://developers.bead.xyz/onboarding/submit-application.md)

How to create full and short onboarding applications with the original single call endpoints.

Includes request structure, signer guidance, `submitImmediately`, `skipPartnerReview`, response examples, and the difference between immediate-submit and Draft application creation.

[**Send to Applicant**](https://developers.bead.xyz/onboarding/send-to-applicant.md)

How to send a prepared application to the applicant for the first time.

Use this page when an application is in `prepared`. It covers what send does, edits before you send, timeouts, and error handling.

[**Fee Configuration for Onboarding Applications**](https://developers.bead.xyz/onboarding/fee-configuration-for-onboarding-applications.md)

How to structure settlement, crypto, and digital wallet pricing in onboarding requests.

Use this page before submitting applications so the signer sees the correct fee configuration.

[**Application Attachments**](https://developers.bead.xyz/onboarding/application-attachments.md)

How to upload, list, download, and delete supporting documents while an application is in Draft, prepared, or changesRequested status.

Use this page when you have documents to include before signature.

[**Test the Full Onboarding Workflow in Sandbox**](https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)

Step-by-step guidance for running an end-to-end Sandbox onboarding test, including the send step, signer completion, status tracking, webhook validation, and the Sandbox manual-advance step.

[**Get Status**](https://developers.bead.xyz/onboarding/get-status.md)

How to retrieve the current onboarding application state and interpret lifecycle statuses such as `draft`, `prepared`, `signing`, `signed`, `reviewing`, `boarding`, and `boarded`.

[**List Applications**](https://developers.bead.xyz/onboarding/list-applications.md)

How to retrieve a paginated, filterable list of onboarding applications for a partner and its descendants.

Use this page when you need to find or monitor applications across a partner hierarchy rather than look up a single known `applicationId`.

[**Resend Application**](https://developers.bead.xyz/onboarding/resend-application.md)

How to email the applicant their invitation again, with the same link.

Use this page when an application is in `signing` and the applicant needs the email again.

[**Webhooks for Application Events**](https://developers.bead.xyz/onboarding/partner-webhooks.md)

How to subscribe to onboarding application events and process them safely.

[**Sample Payload**](https://developers.bead.xyz/onboarding/sample-payload.md)

Example request bodies for the Draft endpoint, the short application, full application, and common fee configurations.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/onboarding.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
