> 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 ## 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. | 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: 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"`. This value cannot be changed after boarding without a full application resubmission. 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"`. This value cannot be changed after boarding without a full application resubmission. 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. ### 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.** A `"physical"`-only boarding cannot be changed post-boarding without resubmission. * 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. ### 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) --- # 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.