# Application Attachments Use application attachments to upload supporting documents to a merchant onboarding application before the signer receives the application. Attachments are only available for applications in Draft status. To create an application in Draft status, set `submitImmediately` to `false` when you create the application. After all required attachments are uploaded, submit the Draft application for signature. ```http POST /merchant-onboarding/applications/{applicationId}/submit ``` ### When to use attachments Use attachments when you need to provide supporting documents before the application is sent to the signer. 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. ### Attachment workflow The attachment workflow has four steps. 1. Create the application in Draft status. ```json { "submitImmediately": false, "merchantData": { "...": "..." } } ``` 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 for signature. ```http POST /merchant-onboarding/applications/{applicationId}/submit ``` After the application leaves Draft status, attachments can no longer be added or deleted. ### Create the application in Draft status Set `submitImmediately` to `false` when creating the application. ```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 } ], "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. ```json { "applicationId": "app_123", "envelopeId": "env_456", "status": "draft" } ``` ### Upload an attachment Upload an attachment to a Draft application. ```http POST /merchant-onboarding/applications/{applicationId}/attachments ``` Each upload includes: | Field | Required | Description | | ------------------ | ----------- | --------------------------------------------------------------- | | `file` | Yes | The PDF, JPEG, or PNG document to upload. | | `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.png" \ --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` ### 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.png", "contentType": "image/png", "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 submitting the Draft application for signature. ### 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 a Draft application. ```http DELETE /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId} ``` A successful delete returns: ```http 204 No Content ``` Deleting attachments is only allowed while the application is still in Draft status. After the application is submitted for signature, attachments cannot be deleted. ### Replacing an attachment There is no separate update attachment command. To replace an attachment while the application is still in Draft 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 ``` ### Submit the Draft application After all required attachments are uploaded, submit the Draft application for signature. ```http POST /merchant-onboarding/applications/{applicationId}/submit ``` This sends the application to the signer and starts the signing flow. After this step, the application is no longer in Draft status and attachments can no longer be added or deleted. ### Error handling | Scenario | Expected result | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Uploading an attachment to a non-Draft application | The request fails because attachments can only be added in Draft status. | | Deleting an attachment after submission | The request fails because attachments can only be deleted in Draft 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 an unsupported file type | The request fails validation. | | Downloading an unknown `attachmentId` | The request returns not found. | ### Best practices * Create the application with `submitImmediately: false` whenever attachments are required. * Upload all required documents before submitting the Draft application for signature. * 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 submission. * Submit the Draft 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 * [Submit Application](/onboarding/submit-application.md) * [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md) * [Test the Full Onboarding Workflow in Sandbox](/onboarding/test-the-full-onboarding-workflow-in-sandbox.md) * [Get Status](/onboarding/get-status.md) * [Resend Application](/onboarding/resend-application.md) * [Webhooks for Application Events](/onboarding/webhooks-for-application-events.md) * [Sample Payload](/onboarding/sample-payload.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/application-attachments.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.