Ctrlk
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:

  • 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 sent to the signer immediately or created in Draft status

  • upload supporting documents before signature when using the Draft attachment flow

  • route the signer through Bead’s hosted onboarding and signing experience

  • track application progress and current status

  • resubmit or follow up on existing applications

  • subscribe to webhook events for application lifecycle updates

Two onboarding submission patterns

There are two primary ways to initiate onboarding through the API.

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 sent to the signer immediately or created in Draft status

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

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

Both submission patterns rely on these key inputs:

  • signer details

  • fee information

  • cryptoEnvironment

  • submitImmediately

For 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 created.

cryptoEnvironment should match the environment you are working in, such as sandbox for Sandbox testing and production for Production onboarding.

submitImmediately controls whether the application is sent to the signer immediately or created 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: true for the simplest onboarding flow.

Use submitImmediately: false when you need to upload supporting documents before sending the application for signature.

High-level onboarding flow

A typical onboarding workflow depends on whether you submit the application immediately or create it in Draft status first.

Immediate-submit flow

Use this flow when attachments are not required before signature.

  1. Create the application.

Use submitImmediately: true, or omit the field if you want the default immediate-submit behavior.

  1. Bead sends the application to the signer.

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:

Draft and attachment flow

Use this flow when you need to upload documents before the signer receives the application.

  1. Create the application with submitImmediately: false.

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

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

  1. Submit the Draft application for signature.

  1. Track progress.

After the Draft application is submitted, track status and webhooks the same way as the immediate-submit flow.

A typical status path may look like:

Application identifiers

Both create endpoints return a response that includes:

  • applicationId

  • envelopeId

  • status

Store applicationId and envelopeId so you can track status, reconcile activity, submit Draft applications, resend applications, and support follow-up workflows later.

Core onboarding endpoints

The core merchant onboarding endpoints are:

Submit, Draft submit, and Resend

These commands are related but serve different purposes.

Action
Endpoint
Use when

Create and immediately send

POST /merchant-onboarding/applications or POST /merchant-onboarding/applications-short with submitImmediately: true

You want Bead to create the application and send it to the signer immediately.

Create Draft

POST /merchant-onboarding/applications or POST /merchant-onboarding/applications-short with submitImmediately: false

You need the application to stay in Draft status so attachments can be uploaded before signature.

Submit Draft

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

The application is in Draft status and is ready to be sent to the signer for the first time.

Resend existing application

PUT /merchant-onboarding/applications/{applicationId}

The application already entered the signer-facing flow and needs to be sent back to the same signer.

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. Decide whether the full or short application flow is the better fit for your use case.

  3. Decide whether your application should be sent immediately or created in Draft status.

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

  5. If you need supporting documents before signature, review Application Attachments.

  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.

Related pages

Submit Application

How to create full and short onboarding applications.

Includes request structure, signer guidance, submitImmediately, response examples, and the difference between immediate-submit and Draft application creation.

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 for Draft applications.

Use this page when creating applications with submitImmediately: false.

Test the Full Onboarding Workflow in Sandbox

Step-by-step guidance for running an end-to-end Sandbox onboarding test, including 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, signing, signed, reviewing, boarding, and boarded.

Resend Application

How to resend an existing application to the same signer.

Use this page when an application has already entered the signer-facing flow and needs follow-up.

Webhooks for Application Events

How to subscribe to onboarding application events and process them safely.

Sample Payload

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

PreviousTest Crypto TransactionsNextSubmit Application

Last updated