> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/onboarding/get-status.md).

# 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

```http
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.

```http
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](#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

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

#### Example response

```json
{
  "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](#onboarding-exceptions) for how to find out why.

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

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

```http
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:

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

Example `onboardingExceptions` entry:

```json
{
  "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.

```http
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:

<table><thead><tr><th width="142">Status</th><th>How to handle</th></tr></thead><tbody><tr><td><code>boarded</code></td><td>Store <code>onboardedMerchantId</code> and proceed with downstream merchant setup or usage.</td></tr><tr><td><code>withdrawn</code></td><td>Stop normal onboarding automation for this application.</td></tr><tr><td><code>rejected</code></td><td>Stop normal onboarding automation, check <code>onboardingExceptions</code> for the reason, and review next steps with your Bead team.</td></tr></tbody></table>

#### 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](/onboarding/submit-application.md)
* [Application Attachments](/onboarding/application-attachments.md)
* [Test the Full Onboarding Workflow in Sandbox](/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)
* [Resend Application](/onboarding/resend-application.md)
* [Webhooks for Application Events](/onboarding/webhooks-for-application-events.md)
* [Sample Payload](/onboarding/sample-payload.md)
* [Reference Guide](/reference-guide.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/onboarding/get-status.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.