> 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
* detect that an application needs changes or was rejected (the reason for a change request is sent in the `applicationChangesRequested` webhook)
* 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` | Present on every response. For API integrations it is always an empty array. See [Why an application needs changes](#why-an-application-needs-changes) for how to find out why an application needs attention. |

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

The application `id` is the identifier to store and use. Any envelope identifier returned when an application is created is an internal signing reference and is not needed for any Bead API call.

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

> **Status casing.** This endpoint and the list endpoint currently return `status` with an initial capital letter, for example `Signing` or `ChangesRequested`. Webhook payloads use camelCase, for example `signing` or `changesRequested`. The status names in this page are written in camelCase. Compare status values without regard to case, and do not depend on one casing.

There is no `failed` status. An application that needs correction or was declined moves to `changesRequested` or `rejected` instead. See [Why an application needs changes](#why-an-application-needs-changes) for how to find out why.

| Status             | Meaning                                                                                                                                                                                | Typical next step                                                                                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `draft`            | The application was created but has not been submitted yet. This is usually created with `submitImmediately: false`, or with the Draft endpoint.                                       | Upload attachments if needed, then submit the Draft application.                                                                                                  |
| `submitted`        | The application has been submitted into the onboarding workflow.                                                                                                                       | Continue monitoring status or webhooks.                                                                                                                           |
| `preparing`        | Bead is gathering business information for the application after it was submitted.                                                                                                     | Wait. No action is needed.                                                                                                                                        |
| `prepared`         | The application is ready to be sent to the applicant. It waits here until someone sends it, unless it was created with skip partner review, in which case Bead sends it automatically. | Review and correct the application if needed, then call [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md).                         |
| `changesRequested` | Additional information or correction is needed. The reason is sent in the `applicationChangesRequested` webhook, in `data.reason`.                                                     | Do not call send or resend. Read the reason from the webhook and correct what it names. See Resolving changesRequested below.                                     |
| `resubmitted`      | A previously returned or changed application has been resubmitted.                                                                                                                     | Continue monitoring status or webhooks.                                                                                                                           |
| `signing`          | The application has been sent to the applicant and is awaiting completion.                                                                                                             | Wait for the applicant to finish. If the applicant needs the email again, use [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md). |
| `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.                                                                                                  |
| `expired`          | The applicant did not finish before the invitation expired.                                                                                                                            | Resend does not apply to this status. Contact your Bead team to reach the applicant again.                                                                        |
| `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. No rejection reason is provided through the API, and no webhook is sent.                                          | Contact your Bead team to determine next steps.                                                                                                                   |

These are the values `status` can return today: `draft`, `submitted`, `preparing`, `prepared`, `changesRequested`, `resubmitted`, `signing`, `signed`, `reviewing`, `reviewed`, `viewed`, `boarding`, `boarded`, `expired`, `withdrawn`, and `rejected`.

Additional status values may be added over time. Existing statuses keep their current meaning when new ones are introduced. Build your integration to tolerate a `status` value it does not recognize: log it, keep the last state you recognized, and do not fail. Check again later, or use webhooks, to pick up the next status.

#### Send and resend by status

Sending the application to the applicant is its own step, and each of the two calls works for exactly one status.

| Application status | Call                                                            | Result                                                                                                                                                                          |
| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prepared`         | `POST /merchant-onboarding/{applicationId}/send-to-applicant`   | First send. The application moves to `signing`. See [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md).                                           |
| `signing`          | `POST /merchant-onboarding/{applicationId}/resend-to-applicant` | The invitation is emailed again with the same link. The application stays in `signing`. See [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md). |
| Any other status   | Neither                                                         | Both return `400` with the current status.                                                                                                                                      |

#### 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, Bead submits the application right away. It moves to `preparing` and then `prepared`, the same as a submitted Draft. It is then sent to the signer automatically when skip partner review applies, or when you call send.

A typical flow may look like:

```
preparing → prepared → signing → signed → reviewing → reviewed → boarding → boarded
```

Use this path for the simplest onboarding workflow test. Set `skipPartnerReview` to `true` if you want the application sent without a separate call.

**Draft and Submit flow**

When an application is created as a Draft, it stays in Draft status until you submit it. After submit, Bead gathers business information, and the application waits in `prepared` until someone sends it to the applicant.

A typical flow may look like:

```
draft → preparing → prepared → signing → signed → reviewing → reviewed → boarding → boarded
```

Use this path when attachments need to be added, or when a person on your side reviews the application, before the applicant receives it.

After attachments are uploaded, submit the Draft application:

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

When the application reaches `prepared`, send it to the applicant:

```http
POST /merchant-onboarding/{applicationId}/send-to-applicant
```

An application created with skip partner review is sent automatically at `prepared`, so you do not call send for it.

#### How to use the response

A common pattern is:

* use `status` to understand the overall application state
* use the `applicationChangesRequested` webhook to learn *why* an application needs changes
* 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. It also covers the case where an onboarding webhook delivery is dropped after its short retry window. See [Partner Webhooks](https://developers.bead.xyz/onboarding/partner-webhooks.md).

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

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.

Where these details carry their own `status` value, the possible values are:

| Detail                      | Possible `status` values                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agreementApplication`      | `unsent`, `sent`, `completed`, `correct`, `created`, `declined`, `deleted`, `delivered`, `signed`, `template`, `timedOut`, `voided`, `resent`, `failed` |
| `bankingApplication`        | `pending`, `boarded`, `failed`                                                                                                                          |
| `cryptoServicesApplication` | `customerCreated`, `customerActivated`, `failed`                                                                                                        |

Treat these as diagnostic detail. The overall application `status` remains the source of truth for where the application stands.

#### Why an application needs changes

For API integrations, the reason an application needs changes is delivered in the `applicationChangesRequested` webhook, in the `data.reason` field. Store it when the event arrives, and show it to the merchant or reseller in your own portal or workflow. See [Partner Webhooks](https://developers.bead.xyz/onboarding/partner-webhooks.md) for the payload.

Two other places might look like they carry the reason, but they do not for API integrations:

* `onboardingExceptions` on this endpoint is always returned as an empty array.
* Application history notes contain standard summary text only, for example "Application returned for changes before boarding". They do not describe what needs to be corrected.

A rejected application has no webhook and no reason through the API. Detect it by checking `status`, and contact your Bead team for next steps.

Bead does not send email or other notifications to the signer or the partner when an application moves to `changesRequested`, `rejected`, or `boarded`. Use webhooks and this endpoint to drive any notifications in your own system.

#### Onboarding exceptions

`onboardingExceptions` is returned directly on this endpoint. There is no separate exceptions endpoint. The field is always present on the response.

Detailed exception records are internal to Bead. For API integrations the array is returned empty, including when the application is in `changesRequested` or `rejected`. An empty array does not mean the application is moving forward, so always check `status`, and use the `applicationChangesRequested` webhook to learn the reason an application needs changes.

#### Resolving changesRequested

An application in `changesRequested` does not move forward on its own. Send and resend do not apply to this status, and both return `400`.

To resolve it:

1. Read the reason from the `data.reason` field of the `applicationChangesRequested` webhook. The reason is not available through this endpoint or the application history. If you missed the event, contact your Bead team.
2. Pass the reason on to the merchant or reseller in your own portal or workflow, so they know exactly what to correct.
3. Correct what the reason names. You can upload replacement documents while the application is in this status. See [Application Attachments](https://developers.bead.xyz/onboarding/application-attachments.md).
4. Contact your Bead team to move the application forward.
5. Keep checking status until the application moves on.

An `applicationChangesRequested` webhook is sent when an application enters this state, if your registration includes that event type. Because a dropped webhook delivery is not resent, store the reason when the event arrives.

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

The response is an array with one entry for each change. Each entry has these fields:

| Field           | Type           | Description                                                                                                                                               |
| --------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applicationId` | string         | The application the entry belongs to.                                                                                                                     |
| `action`        | string         | What happened, for example a status change or a resend.                                                                                                   |
| `fromStatus`    | string or null | The `status` before the change. `null` when there was no earlier status.                                                                                  |
| `toStatus`      | string         | The `status` after the change. Uses the same values as the status table above.                                                                            |
| `performedBy`   | string or null | Who or what made the change. Not returned to API integrations, so expect `null`.                                                                          |
| `notes`         | string or null | Free text recorded with the change. For API integrations this is standard summary text only. It does not include the reason an application needs changes. |
| `timestamp`     | string         | When the change happened, in UTC ISO-8601 format.                                                                                                         |

Example history entry:

```json
{
  "applicationId": "app-123exampleid",
  "action": "statusChanged",
  "fromStatus": "reviewing",
  "toStatus": "changesRequested",
  "performedBy": null,
  "notes": "Application returned for changes before boarding",
  "timestamp": "2026-08-20T14:32:00Z"
}
```

#### 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. No reason is provided through the API, so contact your Bead team to review next steps. |

#### Best practices

* Store `applicationId` when the application is created.
* Use `applicationId` as the primary lookup key for status checks.
* Compare `status` values without regard to case. This endpoint currently returns a capitalized first letter, and webhook payloads use camelCase.
* Store the `data.reason` from every `applicationChangesRequested` webhook. It is the only place the reason is provided to API integrations.
* Do not rely on `onboardingExceptions` or application history notes to explain why an application needs changes.
* 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. Treat an unrecognized `status` value as informational rather than an error.
* Call send only when the status is `prepared`, and resend only when it is `signing`.
* Display clear internal support states for `changesRequested`, `expired`, `withdrawn`, and `rejected`, using the reason you stored from the webhook for `changesRequested`.
* For Sandbox testing, remember that some steps may require manual advancement by your Bead team.

**Related pages**

* [Submit Application](https://developers.bead.xyz/onboarding/submit-application.md)
* [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md)
* [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md)
* [Application Attachments](https://developers.bead.xyz/onboarding/application-attachments.md)
* [Test the Full Onboarding Workflow in Sandbox](https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)
* [Partner Webhooks](https://developers.bead.xyz/onboarding/partner-webhooks.md)
* [Sample Payload](https://developers.bead.xyz/onboarding/sample-payload.md)
* [Reference Guide](https://developers.bead.xyz/reference-guide)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
