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

• find out why an application needs attention, using onboardingExceptions

• 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.
onboardingExceptions	Array of exceptions raised against the application. Empty when there is nothing to review. See Onboarding exceptions below.

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",
  "onboardingExceptions": []
}

Understanding application status

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

There is no failed status. An application that needs correction or was declined moves to changesRequested or rejected instead — see Onboarding exceptions for how to find out why.

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. Check onboardingExceptions for the specific reason.	Review the exception, 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.
viewed	The signer has opened the application.	Continue monitoring status or webhooks.
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. Check onboardingExceptions for the reason.	Review the exception 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 onboardingExceptions to understand why the application needs attention, particularly at changesRequested or rejected

• 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

onboardingExceptions is returned directly on this endpoint — there is no separate exceptions endpoint. It is always present on the response (an empty array when there is nothing to review), so it's safe to check on every call.

If the array is non-empty, review it before assuming the application is stalled. Each entry describes one exception:

Field	Description
applicationId	The application the exception belongs to.
status	Exception status: open, inProgress, or resolved.
onboardingStep	The application status the exception was raised at (uses the same values as the status table above).
exceptionType	The kind of exception: validationError, integrationFailure, or crosswalkGap.
errorMessage	Human-readable description of the problem.
timestamp	When the exception was raised.
assignedTo	Who the exception is currently assigned to.
resolutionNotes	Array of notes logged while working the exception, each with author, note, and timestamp.

Example onboardingExceptions entry:

{
  "onboardingExceptions": [
    {
      "applicationId": "app-123exampleid",
      "status": "open",
      "onboardingStep": "reviewing",
      "exceptionType": "validationError",
      "errorMessage": "Provided EIN does not match records on file.",
      "timestamp": "2026-08-20T14:32:00Z",
      "assignedTo": "compliance-team",
      "resolutionNotes": []
    }
  ]
}

Common operational handling:

• check onboardingExceptions any time status is changesRequested or rejected, and any time the application appears stalled

• use exceptionType and errorMessage to show a clear internal support state, and to distinguish a merchant-fixable issue (validationError) from an internal one (integrationFailure, crosswalkGap)

• avoid asking the merchant to resubmit blindly — use errorMessage to tell them what to correct

• treat status: open or inProgress as still being worked; resolved means the exception itself is closed, though the application may still require further action

• 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, check onboardingExceptions for the reason, and review 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.

• Check onboardingExceptions on every response, not only when status looks stuck — it is always present (possibly empty).

• 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, driven by onboardingExceptions where available.

• 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