> 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 Create a new merchant onboarding application through the API. 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 immediately sends it to the signer. If you need to upload supporting documents before the signer receives the application, 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 sending it to the signer 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 For both 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` and `envelopeId` #### Authentication and headers Onboarding requests use API key authentication. #### Submit behavior Use `submitImmediately` to control whether Bead sends the application to the signer immediately or creates it in Draft status.
ValueBehavior
omittedBead preserves the existing default behavior and sends the application to the signer immediately.
trueBead creates the application and immediately starts the signer flow.
falseBead creates the application in Draft status so attachments can be uploaded before the signer receives it.
Use `submitImmediately: false` when you need to upload supporting documents through the attachment endpoints before sending the application for signature. After all required attachments have been uploaded, call: ``` POST /merchant-onboarding/applications/{applicationId}/submit ``` This submits the Draft application for signature and starts the DocuSign signing flow. The latest OpenAPI includes this dedicated Draft submit endpoint, separate from the resend/resubmit endpoint. #### 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-send behavior > **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](/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 sends it to the signer. You can omit `submitImmediately` when you want the default immediate-send behavior. **Example: create Draft application for attachments** Use this pattern when you need to upload documents before the signer receives the application. After creating the Draft application, upload attachments while the application is still in Draft status. Then submit the Draft application for signature: ``` POST /merchant-onboarding/applications/{applicationId}/submit ``` Attachments can only be added while the application is in Draft status, and deleting attachments is also limited to Draft applications. #### 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` > **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](/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 creates the related signing package. 3. Bead sends the package to the signer. 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. Bead sends the package to the signer. 6. You track progress using the status endpoints and application event webhooks. #### Typical response fields A successful response includes: * `applicationId` * `envelopeId` * `status` Store `applicationId` and `envelopeId` so you can track, submit, resend, or troubleshoot the application later. For applications submitted immediately, the returned status may reflect the sent or signing state. #### 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 submit 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 → 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](/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](/reference-guide/core-concepts/error-codes.md) and [How do I resolve a 400 ValidationError?](/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-resolve-a-400-validationerror.md) — those pages are being reconciled separately. #### Best practices * 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 signer receives the application. * 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, 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 * [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md) * [Application Attachments](/onboarding/application-attachments.md) * [Get Status](/onboarding/get-status.md) * [Resend Application](/onboarding/resend-application.md) * [Webhooks for Application Events](/onboarding/webhooks-for-application-events.md) * [Sample Payload](/onboarding/sample-payload.md) * [Test the Full Onboarding Workflow in Sandbox](/onboarding/test-the-full-onboarding-workflow-in-sandbox.md) * [Field Validation Rules](/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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/onboarding/submit-application.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.