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.
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:
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.
In the Draft and Submit flow:
the request body wraps all merchant fields in
merchantDatathe signer is identified within
merchantData.stakeholderswithisApplicationSigner: trueformat 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) 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:
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
merchantDatamerchant identity, business details, stakeholder data, banking details, fee information, and
cryptoEnvironmentare included inmerchantDatathe signer is identified within
merchantData.stakeholdersthe stakeholder who should sign is marked with
isApplicationSigner: truesubmitImmediatelycontrols whether the application is submitted immediately or created in Draft statusskipPartnerReviewcontrols whether Bead sends the application to the applicant automatically when it reachesprepared
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:
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:
merchantNamepartnerIdpartnerMidsignerFirstNamesignerLastNamesignerEmailfeeInformationcryptoEnvironmentsubmitImmediatelyskipPartnerReview(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.
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)
Create the Draft with the data you have.
Optionally update the Draft as you collect more data.
Optionally upload attachments while the application is in Draft status.
Optionally list or download attachments to verify the package.
Submit the Draft.
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.
Review, correct if needed, and send to the 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.
If the applicant needs the email again, resend it.
Resend works only while the application is in signing.
Track progress.
Track application progress by polling Get Status, using webhooks, or both.
Continue through review and boarding.
After signature, the application moves through review and downstream boarding.
A typical status path may look like:
Single call flow with immediate submit
Use this flow if you already integrated with the create endpoints and attachments are not required before submit.
Create the application.
Use submitImmediately: true, or omit the field if you want the default immediate submit behavior. The response returns applicationId.
Bead prepares the application.
The application moves to preparing while Bead gathers business information, then to prepared.
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.
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.
Track progress.
Track application progress by polling Get Status, using webhooks, or both.
Continue through review and boarding.
After signature, the application moves through review and downstream boarding.
A typical status path may look like:
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.
Create the application with
submitImmediately: false.
Upload attachments while the application is in Draft status.
Submit the Draft application.
Send the prepared application to the applicant, then track progress the same way as the other flows.
Application identifiers
All create endpoints return a response that includes applicationId. The submit command returns:
applicationIdenvelopeId
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:
Create, Submit, Discard, Send, and Resend
These commands are related but serve different purposes.
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:
Implement Onboarding
Implement Entity Management
Implement Payments
Implement Reporting and Settlement
Getting started
Before you build your onboarding integration:
Obtain your onboarding API key.
Start with Draft and Submit. Review Draft and Submit (Recommended) for the flow and a complete sample.
Decide which merchant data you will send at Draft creation and which you will add later with an update.
Review Fee Configuration for Onboarding Applications so your submitted fees match the merchant's commercial agreement.
If you have supporting documents, review Application Attachments and upload them while the application is a Draft or prepared.
Review the onboarding request and response models in the Reference Guide.
Decide how your system will track status changes, whether by polling, webhooks, or both.
Make sure your integration sets
cryptoEnvironmentcorrectly for the target environment.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)
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.
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.
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
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.
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
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.
How to retrieve the current onboarding application state and interpret lifecycle statuses such as draft, prepared, signing, signed, reviewing, boarding, and boarded.
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.
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
How to subscribe to onboarding application events and process them safely.
Example request bodies for the Draft endpoint, the short application, full application, and common fee configurations.
Last updated