> 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/submit-application.md).

# Submit Application

{% hint style="success" %}
**Starting a new integration?** Use [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md). Save a Draft with `POST /merchant-onboarding/applications/drafts`, attach files if you have them, then call `POST /merchant-onboarding/applications/{applicationId}/submit`. The endpoints on this page remain available and fully supported for integrations that already use them.
{% endhint %}

Create a new merchant onboarding application through the API with a single call.

Two submission patterns are available:

* a full application with merchant data prefilled in your request
* a short application that starts the onboarding process with a smaller payload and lets the hosted onboarding flow collect the remaining information

By default, Bead creates the application and submits it in the same call. The application then moves to `preparing` while Bead gathers business information, and to `prepared`. From `prepared` it is sent to the applicant, either by you with [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md) or automatically when skip partner review applies. If you need to upload supporting documents before the application is submitted, set `submitImmediately` to `false` so the application is created in Draft status.

For the full application flow, identify the signer inside `merchantData.stakeholders` by setting `isApplicationSigner` to `true`.

For the short application flow, send signer details using `signerFirstName`, `signerLastName`, and `signerEmail`.

#### Choosing a flow

Choose `POST /merchant-onboarding/applications` when:

* your system already has merchant business, ownership, banking, and fee information
* you want to prefill the onboarding package as much as possible
* you want the signer to mainly review, confirm, and sign
* you may need to create the application in Draft status and upload attachments before submitting it

Choose `POST /merchant-onboarding/applications-short` when:

* you want a lighter-weight entry point
* you want the hosted onboarding flow to collect most of the remaining merchant information
* you still want to provide signer details, fee information, and crypto environment up front

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

* you want one pattern that works whether you have complete or partial merchant data
* you want to save data as you collect it and submit the application later
* you want to upload attachments before submit without setting `submitImmediately`

For all flows:

* provide the required fee configuration
* set `cryptoEnvironment` correctly for the environment you are using
* decide whether to submit immediately or create the application in Draft status
* store the returned `applicationId`

#### Authentication and headers

Onboarding requests use API key authentication.

#### Submit behavior

Use `submitImmediately` to control whether Bead submits the application when it is created or creates it in Draft status.

<table><thead><tr><th width="136">Value</th><th>Behavior</th></tr></thead><tbody><tr><td>omitted</td><td>Bead preserves the existing default behavior and submits the application immediately.</td></tr><tr><td><code>true</code></td><td>Bead creates the application and submits it. The application moves to <code>preparing</code>, then <code>prepared</code>.</td></tr><tr><td><code>false</code></td><td>Bead creates the application in Draft status so attachments can be uploaded before you submit it.</td></tr></tbody></table>

Use `submitImmediately: false` when you need to upload supporting documents through the attachment endpoints before the application is submitted. The dedicated Draft endpoint, `POST /merchant-onboarding/applications/drafts`, is the recommended way to create a Draft. See [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md).

After all required attachments have been uploaded, call:

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

This submits the Draft application. It moves to `preparing`, then `prepared`, and waits there to be sent to the applicant. This submit endpoint is separate from the send and resend endpoints.

#### Skip partner review

By default, a submitted application waits in `prepared` until someone calls [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md). This is the point where a person on your side reviews and corrects the application.

Set `skipPartnerReview` to `true` on the create request to have Bead send the application to the applicant automatically when it reaches `prepared`. Set it to `false` to hold the application for your review. When you omit the field, Bead applies the default for the environment, so set it explicitly when your integration depends on one behavior. If the automatic send fails, the application stays in `prepared` and you can call send yourself.

#### Full application

The full application flow is designed for partners that want to submit a more complete onboarding request from their own system.

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

**Signer guidance**

For the full application flow, the signer is identified in `merchantData.stakeholders`.

Set `isApplicationSigner` to `true` for the stakeholder who should receive and sign the application.

Only one stakeholder should be designated as the application signer.

**What to include**

A full application typically includes:

* merchant identity and business details in `merchantData`
* contact and point-of-contact information
* stakeholder and ownership details
* banking and settlement details
* fee configuration
* crypto environment
* `submitImmediately` when you want to explicitly control Draft vs. immediate submit behavior
* `skipPartnerReview` when you want to control whether the application is sent to the applicant automatically

> **Set `locationBusinessType` carefully.** This field determines which payment connections are provisioned for the merchant at boarding time. Setting it to `"physical"` means virtual wallet connections (Klarna, USDC, Lightning, etc.) will not be built — Virtual terminals using those tenders will fail to create. If the merchant needs to accept virtual wallet payments, use `"virtual"` or `"both"`. The value can still change while the application is in flight — what matters is the value at boarding. Adding an environment after boarding is account maintenance, not a resubmission, but it will likely trigger a new compliance review for the added environment, so it still pays to get this right up front. See [Location Management](https://developers.bead.xyz/entity-management/location-management.md) for the full value breakdown and impact table.

**Example: submit immediately**

This example shows the default one-step flow. Bead creates the application and submits it. The application then moves to `preparing` and `prepared`.

You can omit `submitImmediately` when you want the default immediate submit behavior.

**Example: create Draft application for attachments**

Use this pattern when you need to upload documents before the application is submitted.

After creating the Draft application, upload attachments while the application is still in Draft status.

Then submit the Draft application:

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

Attachments can be added or deleted while the application is in Draft, `prepared`, or `changesRequested` status. See [Application Attachments](https://developers.bead.xyz/onboarding/application-attachments.md).

#### Short application

The short application flow is designed for partners that want to start onboarding quickly and let the hosted onboarding flow collect most of the remaining merchant information.

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

**Signer guidance**

For the short application flow, send signer details as top-level fields:

* `signerFirstName`
* `signerLastName`
* `signerEmail`

**What to include**

A short application typically includes:

* `merchantName`
* `partnerId`
* `partnerMid`
* `signerFirstName`, `signerLastName`, and `signerEmail`
* `feeInformation`
* `cryptoEnvironment`
* `submitImmediately`
* `skipPartnerReview` when you want to control whether the application is sent to the applicant automatically

> **Set `locationBusinessType` carefully.** This field determines which payment connections are provisioned for the merchant at boarding time. Setting it to `"physical"` means virtual wallet connections (Klarna, USDC, Lightning, etc.) will not be built — Virtual terminals using those tenders will fail to create. If the merchant needs to accept virtual wallet payments, use `"virtual"` or `"both"`. The value can still change while the application is in flight — what matters is the value at boarding. Adding an environment after boarding is account maintenance, not a resubmission, but it will likely trigger a new compliance review for the added environment, so it still pays to get this right up front. See [Location Management](https://developers.bead.xyz/entity-management/location-management.md) for the full value breakdown and impact table.

#### What happens next

If `submitImmediately` is omitted or set to `true`:

1. Bead creates the onboarding application record.
2. Bead submits the application. It moves to `preparing` while Bead gathers business information, then to `prepared`.
3. The application is sent to the signer. You call [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md), or Bead sends it automatically when skip partner review applies.
4. The signer completes the hosted onboarding flow.
5. You track progress using the status endpoints and application event webhooks.

If `submitImmediately` is set to `false`:

1. Bead creates the onboarding application record in Draft status.
2. You upload any required attachments.
3. You optionally list or download attachments to verify the package.
4. You submit the Draft application using `POST /merchant-onboarding/applications/{applicationId}/submit`.
5. The application moves to `preparing`, then `prepared`.
6. You send it with [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md), or Bead sends it automatically when skip partner review applies.
7. You track progress using the status endpoints and application event webhooks.

If the applicant needs the email again once the application is in `signing`, use [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md).

#### Typical response fields

A successful create response includes `applicationId`. It does not include a status. Read the current status with `GET /merchant-onboarding/applications/{applicationId}`.

A successful call to `POST /merchant-onboarding/applications/{applicationId}/submit` returns `applicationId` and `envelopeId`.

Store `applicationId` so you can track, submit, send, resend, or troubleshoot the application later. `envelopeId` is an internal signing reference and is not needed for any Bead API call.

#### Error responses

{% hint style="info" %}
**Confirmed for these two endpoints only.** The shape below has been verified against real responses from `POST /merchant-onboarding/applications` and `POST /merchant-onboarding/applications-short`. It has not been confirmed for other onboarding endpoints or for status codes other than `400` on these two. Treat those as unconfirmed until validated.
{% endhint %}

A `400` response from either create endpoint indicates that one or more fields in your request failed validation. The response body is an RFC 9110 Problem Details object, not a Bead-specific envelope:

```json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Customer.FirstName": [
      "The FirstName field is required."
    ]
  },
  "traceId": "00-0000000000000000000000000000000-0000000000000000-00"
}
```

**Fields**

* `type`\
  A URL identifying the RFC 9110 status section for this response (for example, `.../rfc9110#section-15.5.1` for a `400`). Varies by status code, not by which field failed.
* `title`\
  A short, human-readable summary of the error class. For a validation failure, always `"One or more validation errors occurred."`.
* `status`\
  The HTTP status code, duplicated in the body.
* `errors`\
  An object, not an array. Each key is the **PascalCase, dot-delimited path** of the request field that failed, matching the property names in the underlying request model rather than your original JSON casing (for example, `Customer.FirstName` for a nested field). Each value is an **array of message strings** for that field. A field can carry more than one message if it fails more than one rule.
* `traceId`\
  A [W3C trace-context](https://www.w3.org/TR/trace-context/#traceparent-header) formatted identifier. Always include this when contacting Bead support about a validation failure.

**What this means for your integration**

* Don't parse for a `code`, `error`, `message`, or `details` field on a validation response from these two endpoints. They are not present. Parse `errors` as a map of field path to message array.
* Field paths reflect the request's underlying model naming (PascalCase, dot-delimited), which may not exactly match the camelCase field names you sent. Build your field-path matching accordingly, or match on a case-insensitive, delimiter-normalized basis.
* Log `traceId` alongside the failing field paths. Support can look up the exact request by trace ID.
* See [Field Validation Rules](https://developers.bead.xyz/onboarding/field-validation-rules.md) for the full list of checks that can populate `errors`.

This confirmed shape supersedes any different error example previously shown for these two endpoints, including on Error Codes and How do I resolve a 400 ValidationError?. Those pages are being reconciled separately.

#### Best practices

* For new integrations, start with [Draft and Submit](https://developers.bead.xyz/onboarding/draft-and-submit.md).
* Choose the full application flow when you already have reliable onboarding data.
* Choose the short application flow when you want the hosted onboarding experience to collect most of the remaining data.
* For the full application flow, mark one stakeholder in `merchantData.stakeholders` with `isApplicationSigner: true`.
* **Set `locationBusinessType` to `"virtual"` or `"both"` if the merchant needs to accept virtual wallet payments.** Adding an environment after boarding is account maintenance rather than a resubmission, but expect a new compliance review scoped to the added environment, so it's still worth getting right at boarding. Don't default to `"both"` as a hedge: it attracts more scrutiny at review than a scoped, correct selection.
* Use `submitImmediately: false` when you need to upload attachments before the application is submitted.
* Set `skipPartnerReview` explicitly if your integration depends on whether the application is sent automatically.
* After submit, read the status and call [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md) once the application is `prepared`, unless it is sent automatically.
* Upload and verify all required attachments before calling `POST /merchant-onboarding/applications/{applicationId}/submit`.
* Keep fee configuration aligned with your commercial agreement before submitting the application.
* Store the returned identifiers so you can support submit, send, resend, status, webhook, and support workflows.
* Use international phone formatting such as `+15085550100` where applicable.
* Parse `400` responses from these two endpoints as the confirmed `errors` map above, not a `details` array. See [Error responses](#error-responses).

#### Related pages

* [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md)
* [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md)
* [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md)
* [Fee Configuration for Onboarding Applications](https://developers.bead.xyz/onboarding/fee-configuration-for-onboarding-applications.md)
* [Application Attachments](https://developers.bead.xyz/onboarding/application-attachments.md)
* [Get Status](https://developers.bead.xyz/onboarding/get-status.md)
* [Webhooks for Application Events](https://developers.bead.xyz/onboarding/partner-webhooks.md)
* [Sample Payload](https://developers.bead.xyz/onboarding/sample-payload.md)
* [Test the Full Onboarding Workflow in Sandbox](https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)
* [Field Validation Rules](https://developers.bead.xyz/onboarding/field-validation-rules.md)


---

# 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/submit-application.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.
