# 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 ```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. | 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" } ``` ### 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: ```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 `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. ```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: | 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](/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: 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: ``` GET https://developers.bead.xyz/onboarding/get-status.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.