Get Status

Use this endpoint to retrieve the current state of a merchant onboarding application.

This endpoint applies to both:

• Full applications created with POST /merchant-onboarding/applications

• Short applications created with POST /merchant-onboarding/applications-short

Use this endpoint when you need to:

• check the current onboarding status

• confirm whether the signer has completed the application

• determine whether the application is still under review or boarding

• retrieve the onboarded merchant identifier after approval

• support polling, troubleshooting, and reconciliation workflows

Endpoint

GET /merchant-onboarding/applications/{applicationId}

Path parameter

Parameter	Description
applicationId	The onboarding application identifier returned when the application was created.

Authentication and headers

Onboarding requests use API key authentication.

X-Api-Key: {apiKey}
Accept: application/json

Most important response fields

Start with these fields first:

Field	Description
id	The onboarding application identifier.
merchantName	The merchant name associated with the application.
status	Overall onboarding status for the application.
onboardedMerchantId	The merchant identifier created after successful onboarding. This is typically present once the merchant has been boarded.

These fields usually tell you whether the application is still in progress, needs attention, or is ready for downstream merchant setup and usage.

Example request

GET /merchant-onboarding/applications/{applicationId}
X-Api-Key: {apiKey}
Accept: application/json

Example response

{
  "id": "app-123exampleid",
  "merchantName": "Northwind Coffee Roasters",
  "partnerName": "Acme Payments",
  "partnerId": "partner_123",
  "status": "boarded",
  "onboardedMerchantId": "merchant-555000111222"
}

Understanding application status

The status field represents the overall onboarding state of the application.

Status	Meaning	Typical next step
draft	The application was created but has not been sent to the signer yet. This is usually created with submitImmediately: false.	Upload attachments if needed, then submit the Draft application.
submitted	The application has been submitted into the onboarding workflow.	Continue monitoring status or webhooks.
changesRequested	Additional information or correction is needed.	Review the request, collect updated information, and resubmit as needed.
resubmitted	A previously returned or changed application has been resubmitted.	Continue monitoring status or webhooks.
signing	The application has been sent to the signer and is awaiting completion.	Wait for signer completion or follow up with the signer.
signed	The signer has completed the signing flow.	Wait for review and downstream boarding steps.
reviewing	The application is under review.	Monitor for approval, rejection, or request for changes.
reviewed	Review has completed and the application is ready for the next onboarding step.	Continue monitoring for boarding.
boarding	The application has moved into merchant and provider boarding.	Continue monitoring until boarded.
boarded	The merchant has completed onboarding.	Store onboardedMerchantId and use it for downstream workflows.
withdrawn	The application was withdrawn and is no longer moving forward.	Treat as a stopped application.
rejected	The application was rejected and will not board in its current form.	Review rejection details and determine next steps with your Bead team.

Status flow examples

Immediate-submit flow

When an application is created with submitImmediately: true, or when the field is omitted and the default immediate-submit behavior is used, the application is sent to the signer right away.

A typical flow may look like:

signing → signed → reviewing → reviewed → boarding → boarded

Use this path for the simplest onboarding workflow test.

Draft and attachment flow

When an application is created with submitImmediately: false, the application is created in Draft status.

A typical flow may look like:

draft → signing → signed → reviewing → reviewed → boarding → boarded

Use this path when attachments need to be added before the signer receives the application.

After attachments are uploaded, submit the Draft application for signature:

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

How to use the response

A common pattern is:

• use status to understand the overall application state

• use onboardedMerchantId once the merchant is successfully boarded

• use merchantName and id for display, support, and reconciliation workflows

• use webhooks for event-driven updates, then call this endpoint when you need the current full state

When to poll

Polling can be useful during testing, support workflows, and operational dashboards.

Recommended polling guidance:

• Poll during active testing when you are watching a single application move through the workflow.

• Use a reasonable interval, such as every 30 to 60 seconds, instead of tight loops.

• Stop polling once the application reaches a terminal or operationally complete state such as boarded, withdrawn, or rejected.

• Prefer webhooks for production event handling whenever possible.

Webhooks and status checks

Webhooks notify your system that something changed. This status endpoint gives you the current application state.

A recommended production pattern is:

1. Receive an onboarding webhook.

2. Use the webhook payload to identify the applicationId.

3. Call GET /merchant-onboarding/applications/{applicationId}.

4. Update your system using the current response from the status endpoint.

This keeps your system resilient if webhook events arrive out of order, are retried, or only include summary information.

Provider and downstream boarding details

The overall status field is the first field to check, but the response may also include provider or downstream application details.

Depending on the application and enabled services, the response may include information related to:

• agreement or signing status

• compliance or account services status

• banking application status

• crypto services application status

• digital wallet services application status

• onboarding exceptions

Use these details when you need to troubleshoot why an application is not yet boarded or when you need to understand which part of the onboarding process is still in progress.

Onboarding exceptions

If the response includes onboarding exceptions, review them before assuming the application is stalled.

An onboarding exception may indicate that a specific step requires attention, failed validation, or needs manual review.

Common operational handling:

• show a clear internal support state

• avoid asking the merchant to resubmit blindly

• coordinate with your Bead team if the exception is not self-serviceable

• continue checking status after the exception is resolved

Application history

For audit or troubleshooting workflows, use the application history endpoint.

GET /merchant-onboarding/applications/{applicationId}/history

Use history when you need to understand how the application moved between states or when you need to support an operational investigation.

Terminal states

Treat these statuses as terminal or near-terminal for most integration workflows:

Status	How to handle
boarded	Store onboardedMerchantId and proceed with downstream merchant setup or usage.
withdrawn	Stop normal onboarding automation for this application.
rejected	Stop normal onboarding automation and review the reason or next steps with your Bead team.

Best practices

• Store applicationId when the application is created.

• Use applicationId as the primary lookup key for status checks.

• Use lowercase status values exactly as returned by the API.

• Use onboardedMerchantId only after the merchant has successfully boarded.

• Use webhooks for production event handling and this endpoint for current state lookup.

• Avoid tight polling loops.

• Keep status handling flexible so your integration can support new statuses over time.

• Display clear internal support states for changesRequested, withdrawn, and rejected.

• For Sandbox testing, remember that some steps may require manual advancement by your Bead team.

Related pages

• Submit Application

• Application Attachments

• Test the Full Onboarding Workflow in Sandbox

• Resend Application

• Webhooks for Application Events

• Sample Payload

• Reference Guide