> 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/list-applications.md). # List Applications Use this endpoint to retrieve a paginated list of merchant onboarding applications for a specific partner and its descendants. Use this endpoint when you need to: * find applications across a partner hierarchy without knowing individual `applicationId` values * build an operational dashboard or queue of in-progress applications * filter applications by status, date range, or free text search * reconcile application activity for a partner and its downstream sub-partners If you already have an `applicationId` and only need its current state, use [Get Status](/onboarding/get-status.md) instead. #### Endpoint ```http GET /Partners/{id}/applications ``` #### Path parameter | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------ | | `id` | The `partnerId` to scope results to. Returns applications for this partner and its descendants in the partner hierarchy. | #### Query parameters | Parameter | Type | Required | Description | | --------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `From` | date-time | No | Filter by `updatedAt` from this timestamp (ISO 8601 UTC). Defaults to 30 days before `To`. | | `To` | date-time | No | Filter by `updatedAt` up to this timestamp (ISO 8601 UTC). Defaults to the current UTC time. | | `Statuses` | array | No | Filter by one or more application statuses: `draft`, `submitted`, `changesRequested`, `resubmitted`, `signing`, `signed`, `viewed`, `reviewing`, `reviewed`, `boarding`, `boarded`, `withdrawn`, `rejected`. | | `Search` | string | No | Free text search across fields such as merchant name, signer email, or partner external ID. | | `Page` | integer | No | Zero-based page number. Defaults to `0`. | | `PageSize` | integer | No | Number of results per page. Defaults to `50`, max `100`. | | `SortBy` | string | No | Field to sort by. Supported values: `merchantName`, `status`, `updated`. | | `SortDirection` | string | No | `asc` or `desc`. | #### Authentication and headers ```http X-Api-Key: {apiKey} Accept: application/json ``` #### Example request ```bash curl -X GET "https://api.test.devs.beadpay.io/Partners/{id}/applications?Statuses=boarding&Page=0&PageSize=50" \ -H "X-Api-Key: {apiKey}" \ -H "Accept: application/json" ``` #### Successful response — 200 The response is a paginated wrapper containing an array of application objects. ```json { "data": [ { "id": "app-123exampleid", "merchantName": "Northwind Coffee Roasters", "partnerName": "Acme Payments", "partnerId": "partner_123", "isSettlementOnly": false, "isCommissionMerchant": false, "commissionMerchantId": null, "representsPartnerId": null, "status": "boarding", "updated": "2026-07-28T14:32:00.000Z", "signer": { "email": "jane.doe@example.com", "name": "Jane Doe", "firstName": "Jane", "lastName": "Doe", "position": "Owner", "declinedReason": null, "ipAddress": "203.0.113.10", "language": "en", "userAgent": "Mozilla/5.0" }, "onboardedMerchantId": null, "agreementApplication": null, "complianceApplication": null, "accountServicesApplication": null, "bankingApplication": null, "cryptoServicesApplications": null, "digitalWalletServicesApplications": null, "cryptoServicesApplication": null, "digitalWalletServicesApplication": null, "onboardingExceptions": null } ], "total": 1, "page": 0 } ``` #### Response fields | Field | Description | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | Array of application objects. Each object uses the same shape returned by [Get Status](/onboarding/get-status.md): `id`, `merchantName`, `partnerName`, `partnerId`, `status`, `updated`, `signer`, `onboardedMerchantId`, plus provider and downstream boarding detail fields (`agreementApplication`, `complianceApplication`, `accountServicesApplication`, `bankingApplication`, `cryptoServicesApplications`, `digitalWalletServicesApplications`, `onboardingExceptions`) that populate as the application progresses. See Get Status for how to interpret these details. | | `total` | Total number of applications matching the query. | | `page` | Current page number, zero-indexed. | #### Error responses | Code | Condition | | ---- | ---------------------------------------------------------------------- | | 401 | Missing or invalid API key. | | 403 | Authenticated but not permitted to list applications for this partner. | #### Best practices * Scope by the highest-level partner ID that covers all the applications you need — results include descendants automatically, so you don't need to call this once per sub-partner. * Use `Statuses` to filter to the applications you care about (for example, `boarding` or `changesRequested`) rather than paging through the full result set. * Use `Search` to locate a specific application by merchant name, signer email, or partner external ID instead of scanning pages manually. * Store `total` to drive pagination in dashboards or queues. * Use this endpoint for discovery and operational views; once you have an `applicationId`, use [Get Status](/onboarding/get-status.md) for the authoritative current state of that single application. #### A note on the deprecated List Applications endpoint `GET /merchant-onboarding/applications` is deprecated. Use this endpoint, `GET /Partners/{id}/applications`, instead — it returns the same application data, scoped to a partner and its descendants. **Related pages** * [Get Status](/onboarding/get-status.md) * [Submit Application](/onboarding/submit-application.md) * [Resend Application](/onboarding/resend-application.md) * [Partner Management](/entity-management/partner-management.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/list-applications.md?ask=&goal= ``` `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.