> 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/application-attachments.md).

# Application Attachments

Use application attachments to upload supporting documents to a merchant onboarding application before the applicant receives it.

You can upload and delete attachments while the application is in `draft`, `prepared`, or `changesRequested` status. In any other status, including `signing`, the request fails. The recommended way to create an application in Draft status is `POST /merchant-onboarding/applications/drafts`. You can also create a Draft by setting `submitImmediately` to `false` on `POST /merchant-onboarding/applications` or `POST /merchant-onboarding/applications-short`.

After all required attachments are uploaded, submit the Draft application.

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

After submit, the application moves to `preparing`, then `prepared`. It waits in `prepared` until it is sent to the applicant. See [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md).

### When attachments can be added or deleted

| Application status  | Upload or delete attachments                                                          |
| ------------------- | ------------------------------------------------------------------------------------- |
| `draft`             | Yes.                                                                                  |
| `preparing`         | No. Wait for `prepared`.                                                              |
| `prepared`          | Yes. Use this window to add or replace documents during your review, before you send. |
| `changesRequested`  | Yes. Replace the documents the change request names.                                  |
| `signing` and later | No.                                                                                   |

### When to use attachments

Use attachments when you need to provide supporting documents before the application is sent to the applicant.

Common examples include:

* proof of business
* proof of legal or business address
* proof of bank account
* stakeholder proof of identity
* stakeholder proof of address
* a Cash App logo, when applicable
* other supporting documentation requested during onboarding

Attachments are most useful when your system already collects documents from the merchant and you want to include those files with the onboarding package before signature.

### File requirements

| Requirement         | Value                                                                          |
| ------------------- | ------------------------------------------------------------------------------ |
| Accepted file type  | PDF only. JPEG, PNG, and other image formats are not accepted.                 |
| Maximum upload size | 25 MB per file.                                                                |
| Maximum stored size | 10 MB per file. The stored copy of each attachment must fit within this limit. |

Convert images to PDF before uploading, and keep each PDF small enough to meet the stored size limit. A file that is not a PDF, or that exceeds the limits, is rejected.

### Attachment workflow

The attachment workflow has four steps.

1. Create the application in Draft status.

```http
POST /merchant-onboarding/applications/drafts
```

```json
{
  "merchantData": {
    "partnerId": "partner_123",
    "merchantName": "Northwind Coffee Roasters"
  }
}
```

2. Upload one or more attachments.

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

3. Optionally list or download attachments to confirm the package is complete.

```http
GET /merchant-onboarding/applications/{applicationId}/attachments
GET /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}
```

4. Submit the Draft application.

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

If you need to add or replace a document after submit, wait until the application is `prepared` and upload or delete it then, before you send the application to the applicant. Once the application is in `signing`, attachments can no longer be added or deleted.

See [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md) for the complete flow, including a full Draft sample.

### Create the application in Draft status

The recommended method is the Draft endpoint. Send the merchant data you have inside `merchantData`. Only `partnerId` and `merchantName` are required.

```http
POST /merchant-onboarding/applications/drafts
```

If your integration already uses the original create endpoints, set `submitImmediately` to `false` instead.

```http
POST /merchant-onboarding/applications
```

{% code expandable="true" %}

```json
{
  "submitImmediately": false,
  "merchantData": {
    "merchantName": "Northwind Coffee Roasters",
    "partnerId": "partner_123",
    "partnerExternalId": "ext-merchant-2048",
    "registeredName": "Northwind Coffee Roasters LLC",
    "dbaName": "Northwind Coffee Roasters",
    "merchantCategoryCode": "5499",
    "cryptoEnvironment": "sandbox",
    "stakeholders": [
      {
        "firstName": "Morgan",
        "lastName": "Reed",
        "email": "morgan.reed@example.com",
        "phoneNumber": "+15085550101",
        "jobTitle": "Owner",
        "ownershipPercentage": 100,
        "ownershipType": "direct",
        "dateOfBirth": "1987-06-15",
        "citizenship": "US",
        "idType": "passport",
        "idNumber": "123456789",
        "countryOfIssuance": "US",
        "taxIdType": "ssn",
        "taxIdNumber": "123456789",
        "isApplicationSigner": true,
        "proofOfIdentityType": "passport",
        "proofOfAddressType": "utilityBill",
        "address": {
          "address1": "123 Harbor Street",
          "city": "Boston",
          "region": "MA",
          "country": "US",
          "postalCode": "02110"
        }
      }
    ],
    "feeInformation": {
      "achSettlementFixedFee": {
        "sellRate": 1.5,
        "isBilledByPartner": false
      },
      "settlementReturnFixedFee": {
        "sellRate": 15,
        "isBilledByPartner": false
      },
      "monthlyMaintenanceFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      }
    }
  }
}
```

{% endcode %}

A successful Draft response includes the `applicationId`. Use that value for the attachment endpoints and for every later call on the application.

```json
{
  "applicationId": "app_123"
}
```

The response carries only `applicationId`. Read the current status with `GET /merchant-onboarding/applications/{applicationId}`.

### Upload an attachment

Upload an attachment to an application in `draft`, `prepared`, or `changesRequested` status.

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

Each upload includes:

| Field              | Required    | Description                                                     |
| ------------------ | ----------- | --------------------------------------------------------------- |
| `file`             | Yes         | The PDF document to upload. See File requirements above.        |
| `category`         | Yes         | The document category that identifies what the file represents. |
| `stakeholderIndex` | Conditional | Required for stakeholder-specific document categories.          |
| `type`             | Optional    | Optional descriptor when additional context is needed.          |

#### Example upload

```bash
curl --request POST \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/app_123/attachments \
  --header "X-Api-Key: {apiKey}" \
  --form "file=@proof-of-bank-account.pdf" \
  --form "category=proofOfBankAccount"
```

#### Example stakeholder upload

Use `stakeholderIndex` when uploading a stakeholder document.

```bash
curl --request POST \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/app_123/attachments \
  --header "X-Api-Key: {apiKey}" \
  --form "file=@owner-driver-license-front.pdf" \
  --form "category=stakeholderProofOfIdentityFront" \
  --form "stakeholderIndex=0"
```

`stakeholderIndex` is zero-based and maps to the order of `merchantData.stakeholders`.

For example:

* `stakeholderIndex: 0` maps to the first stakeholder in `merchantData.stakeholders`
* `stakeholderIndex: 1` maps to the second stakeholder in `merchantData.stakeholders`

If you update the application with `PUT /merchant-onboarding/applications/drafts/{applicationId}`, keep the stakeholder order consistent so existing `stakeholderIndex` values still point to the right person.

### Attachment categories

Use the category that best describes the uploaded document.

| Category                          | Use for                                                      |
| --------------------------------- | ------------------------------------------------------------ |
| `proofOfBusiness`                 | Business formation or registration documentation.            |
| `legalProofOfAddress`             | Proof for the merchant’s legal address.                      |
| `businessProofOfAddress`          | Proof for the merchant’s business or operating address.      |
| `proofOfBankAccount`              | Bank account proof such as a voided check or bank letter.    |
| `cashAppLogo`                     | Cash App logo documentation, when applicable.                |
| `stakeholderProofOfIdentityFront` | Front image of a stakeholder identity document.              |
| `stakeholderProofOfIdentityBack`  | Back image of a stakeholder identity document.               |
| `stakeholderProofOfAddress`       | Stakeholder proof of address.                                |
| `other`                           | Supporting documentation that does not fit another category. |

Use stakeholder categories only for documents tied to a specific stakeholder. Include `stakeholderIndex` so Bead can associate the attachment with the correct person.

### Attachment metadata

The upload response returns metadata about the attachment.

```json
{
  "id": "att_123",
  "fileName": "proof-of-bank-account.pdf",
  "contentType": "application/pdf",
  "documentCategory": "proofOfBankAccount",
  "stakeholderIndex": null,
  "sizeBytes": 245912,
  "uploadedAt": "2026-05-06T18:30:00Z",
  "uploadedBy": "partner-api"
}
```

Store the returned `id` if you need to download or delete the attachment later.

### List attachments

List all attachments for an application.

```http
GET /merchant-onboarding/applications/{applicationId}/attachments
```

Example response:

```json
[
  {
    "id": "att_123",
    "fileName": "proof-of-bank-account.pdf",
    "contentType": "application/pdf",
    "documentCategory": "proofOfBankAccount",
    "stakeholderIndex": null,
    "sizeBytes": 245912,
    "uploadedAt": "2026-05-06T18:30:00Z",
    "uploadedBy": "partner-api"
  },
  {
    "id": "att_456",
    "fileName": "owner-driver-license-front.pdf",
    "contentType": "application/pdf",
    "documentCategory": "stakeholderProofOfIdentityFront",
    "stakeholderIndex": 0,
    "sizeBytes": 385102,
    "uploadedAt": "2026-05-06T18:31:00Z",
    "uploadedBy": "partner-api"
  }
]
```

Use this endpoint to verify that all required documents were uploaded before you submit the Draft application or send the prepared application.

### Download an attachment

Download a single attachment.

```http
GET /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}
```

Use this endpoint when you need to confirm the uploaded file or support a troubleshooting workflow.

### Delete an attachment

Delete an attachment from an application in `draft`, `prepared`, or `changesRequested` status.

```http
DELETE /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}
```

A successful delete returns:

```http
204 No Content
```

Deleting attachments is allowed only in those three statuses. After the application is sent to the applicant and moves to `signing`, attachments cannot be deleted.

If you discard the whole Draft with `DELETE /merchant-onboarding/applications/drafts/{applicationId}`, all of its attachments are permanently deleted with it.

### Replacing an attachment

There is no separate update attachment command.

To replace an attachment while the application is in `draft`, `prepared`, or `changesRequested` status:

1. Delete the existing attachment.
2. Upload the replacement file.
3. List attachments to confirm the replacement was added.

```http
DELETE /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}
POST /merchant-onboarding/applications/{applicationId}/attachments
GET /merchant-onboarding/applications/{applicationId}/attachments
```

When the application is in `changesRequested`, replace the documents the change request names, then contact your Bead team to move the application forward. Do not call send or resend. See [Get Status](https://developers.bead.xyz/onboarding/get-status.md).

### Submit the Draft application

After all required attachments are uploaded, submit the Draft application.

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

The application moves to `preparing`, then `prepared`. It does not reach the applicant yet. Send it with `POST /merchant-onboarding/{applicationId}/send-to-applicant`, or it is sent automatically when skip partner review applies. See [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md).

You can still add or delete attachments while the application is in `prepared`. After it is sent and moves to `signing`, attachments can no longer be added or deleted.

### Error handling

| Scenario                                                                                  | Expected result                                                                                                                              |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Uploading an attachment in a status other than `draft`, `prepared`, or `changesRequested` | The request fails. The message names the current status.                                                                                     |
| Deleting an attachment in a status other than `draft`, `prepared`, or `changesRequested`  | The request fails. The message names the current status.                                                                                     |
| Uploading without `category`                                                              | The request fails validation.                                                                                                                |
| Uploading a stakeholder document without `stakeholderIndex`                               | The request may fail validation or may not associate the document correctly. Include `stakeholderIndex` for stakeholder-specific categories. |
| Uploading a file that is not a PDF                                                        | The request fails validation.                                                                                                                |
| Uploading a file over the size limits                                                     | The request fails validation.                                                                                                                |
| Downloading an unknown `attachmentId`                                                     | The request returns not found.                                                                                                               |

### Best practices

* Create the application with `POST /merchant-onboarding/applications/drafts` whenever attachments are required.
* Upload all required documents before submitting the Draft application when you can.
* Use the `prepared` window to add or replace documents during your review, before you send.
* Upload PDF files only, and keep each file within the size limits.
* Use the most specific attachment category available.
* Use `stakeholderIndex` for stakeholder proof documents.
* List attachments after upload to confirm the package is complete.
* Delete and re-upload an attachment if a file needs to be replaced before the application is sent.
* Send the application only after the attachment set is complete.
* Store attachment IDs for support and troubleshooting.
* Do not use the `other` category when a more specific category applies.

### Related pages

* [Draft and Submit (Recommended)](https://developers.bead.xyz/onboarding/draft-and-submit.md)
* [Submit Application](https://developers.bead.xyz/onboarding/submit-application.md)
* [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md)
* [Fee Configuration for Onboarding Applications](https://developers.bead.xyz/onboarding/fee-configuration-for-onboarding-applications.md)
* [Test the Full Onboarding Workflow in Sandbox](https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)
* [Get Status](https://developers.bead.xyz/onboarding/get-status.md)
* [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md)
* [Webhooks for Application Events](https://developers.bead.xyz/onboarding/partner-webhooks.md)
* [Sample Payload](https://developers.bead.xyz/onboarding/sample-payload.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 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/application-attachments.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.
