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.

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.

{
  "submitImmediately": false,
  "merchantData": {
    "...": "..."
  }
}

1. Upload one or more attachments.

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

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

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

1. Submit the Draft application for signature.

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.

POST /merchant-onboarding/applications

{
  "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": "[email protected]",
        "phoneNumber": "[phone]",
        "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
      }
    }
  }
}

A successful Draft response includes the applicationId. Use that value for the attachment endpoints.

{
  "applicationId": "app_123",
  "envelopeId": "env_456",
  "status": "draft"
}

Upload an attachment

Upload an attachment to a Draft application.

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

curl --request POST \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/app_123/attachments \
  --header "X-Api-Key: {apiKey}" \
  --form "[email protected]" \
  --form "category=proofOfBankAccount"

Example stakeholder upload

Use stakeholderIndex when uploading a stakeholder document.

curl --request POST \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/app_123/attachments \
  --header "X-Api-Key: {apiKey}" \
  --form "[email protected]" \
  --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.

{
  "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.

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

Example response:

[
  {
    "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.

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.

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

A successful delete returns:

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.

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.

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

• Fee Configuration for Onboarding Applications

• Test the Full Onboarding Workflow in Sandbox

• Get Status

• Resend Application

• Webhooks for Application Events

• Sample Payload