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

* 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 sent to the signer immediately or created in Draft status
* upload supporting documents before signature when using the Draft attachment flow
* route the signer through Bead’s hosted onboarding and signing experience
* track application progress and current status
* resubmit or follow up on existing applications
* subscribe to webhook events for application lifecycle updates

### Two onboarding submission patterns

There are two primary ways to initiate onboarding through the API.

#### 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 sent to the signer immediately or created in Draft status

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`

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

Both submission patterns rely on these key inputs:

* signer details
* fee information
* `cryptoEnvironment`
* `submitImmediately`

For 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 created.

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

`submitImmediately` controls whether the application is sent to the signer immediately or created in Draft status.

| Value   | Behavior                                                                                                   |
| ------- | ---------------------------------------------------------------------------------------------------------- |
| omitted | Bead preserves the existing default behavior and sends the application to the signer immediately.          |
| `true`  | Bead creates the application and immediately starts the signer flow.                                       |
| `false` | Bead creates the application in Draft status so attachments can be uploaded before the signer receives it. |

Use `submitImmediately: true` for the simplest onboarding flow.

Use `submitImmediately: false` when you need to upload supporting documents before sending the application for signature.

### High-level onboarding flow

A typical onboarding workflow depends on whether you submit the application immediately or create it in Draft status first.

#### Immediate-submit flow

Use this flow when attachments are not required before signature.

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.

2. Bead sends the application to the signer.

The signer receives the hosted onboarding and signing experience using the signer details provided in the request.

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

4. Track progress.

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

5. Continue through review and boarding.

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

A typical status path may look like:

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

#### Draft and attachment flow

Use this flow when you need to upload documents before the signer receives the application.

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. Optionally list or download attachments to verify the package.

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

4. Submit the Draft application for signature.

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

5. Track progress.

After the Draft application is submitted, track status and webhooks the same way as the immediate-submit flow.

A typical status path may look like:

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

### Application identifiers

Both create endpoints return a response that includes:

* `applicationId`
* `envelopeId`
* `status`

Store `applicationId` and `envelopeId` so you can track status, reconcile activity, submit Draft applications, resend applications, and support follow-up workflows later.

### Core onboarding endpoints

The core merchant onboarding endpoints are:

```http
POST /merchant-onboarding/applications
POST /merchant-onboarding/applications-short
GET /merchant-onboarding/applications
GET /merchant-onboarding/applications/{applicationId}
POST /merchant-onboarding/applications/{applicationId}/submit
PUT /merchant-onboarding/applications/{applicationId}
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
```

### Submit, Draft submit, and Resend

These commands are related but serve different purposes.

| Action                      | Endpoint                                                                                                                   | Use when                                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Create and immediately send | `POST /merchant-onboarding/applications` or `POST /merchant-onboarding/applications-short` with `submitImmediately: true`  | You want Bead to create the application and send it to the signer immediately.                       |
| Create Draft                | `POST /merchant-onboarding/applications` or `POST /merchant-onboarding/applications-short` with `submitImmediately: false` | You need the application to stay in Draft status so attachments can be uploaded before signature.    |
| Submit Draft                | `POST /merchant-onboarding/applications/{applicationId}/submit`                                                            | The application is in Draft status and is ready to be sent to the signer for the first time.         |
| Resend existing application | `PUT /merchant-onboarding/applications/{applicationId}`                                                                    | The application already entered the signer-facing flow and needs to be sent back to the same signer. |

### 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. Decide whether the full or short application flow is the better fit for your use case.
3. Decide whether your application should be sent immediately or created in Draft status.
4. Review Fee Configuration for Onboarding Applications so your submitted fees match the merchant’s commercial agreement.
5. If you need supporting documents before signature, review Application Attachments.
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.

### Related pages

#### [Submit Application](/onboarding/submit-application.md)

How to create full and short onboarding applications.

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

#### [Fee Configuration for Onboarding Applications](/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](/onboarding/application-attachments.md)

How to upload, list, download, and delete supporting documents for Draft applications.

Use this page when creating applications with `submitImmediately: false`.

#### [Test the Full Onboarding Workflow in Sandbox](/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)

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

#### [Get Status](/onboarding/get-status.md)

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

#### [Resend Application](/onboarding/resend-application.md)

How to resend an existing application to the same signer.

Use this page when an application has already entered the signer-facing flow and needs follow-up.

#### [Webhooks for Application Events](/onboarding/webhooks-for-application-events.md)

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

#### [Sample Payload](/onboarding/sample-payload.md)

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


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.