Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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 merchantData

  • the signer is identified within merchantData.stakeholders with isApplicationSigner: true

  • format 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 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 submitted immediately or created in Draft status

  • skipPartnerReview controls whether Bead sends the application to the applicant automatically when it reaches prepared

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:

  • merchantName

  • partnerId

  • partnerMid

  • signerFirstName

  • signerLastName

  • signerEmail

  • feeInformation

  • cryptoEnvironment

  • submitImmediately

  • skipPartnerReview (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.

Value
Behavior

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)

  1. Create the Draft with the data you have.

  1. Optionally update the Draft as you collect more data.

  1. Optionally upload attachments while the application is in Draft status.

  1. Optionally list or download attachments to verify the package.

  1. Submit the Draft.

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

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

  1. If the applicant needs the email again, resend it.

Resend works only while the application is in signing.

  1. Track progress.

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

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

  1. Create the application.

Use submitImmediately: true, or omit the field if you want the default immediate submit behavior. The response returns applicationId.

  1. Bead prepares the application.

The application moves to preparing while Bead gathers business information, then to prepared.

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

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

  1. Track progress.

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

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

  1. Create the application with submitImmediately: false.

  1. Upload attachments while the application is in Draft status.

  1. Submit the Draft application.

  1. 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:

  • applicationId

  • envelopeId

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.

Action
Endpoint
Use when

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:

  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. Start with Draft and Submit. Review Draft and Submit (Recommended) for the flow and a complete sample.

  3. Decide which merchant data you will send at Draft creation and which you will add later with an update.

  4. Review Fee Configuration for Onboarding Applications so your submitted fees match the merchant's commercial agreement.

  5. If you have supporting documents, review Application Attachments and upload them while the application is a Draft or prepared.

  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.

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.

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.

Submit Application

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.

Send to Applicant

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.

Application Attachments

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.

Get Status

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

List Applications

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.

Resend Application

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.

Sample Payload

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

Last updated