Draft and Submit (Recommended)

Draft and Submit is the recommended way to start every merchant onboarding application.

Collect what you have, save it as a Draft with a single call, attach supporting PDFs if you have them, and submit the application for signature when you are ready. The same pattern works whether you hold a complete merchant profile or only a merchant name.

Recommended starting point. POST /merchant-onboarding/applications and POST /merchant-onboarding/applications-short remain available and fully supported. If you already integrated with either one, nothing changes for you. See Submit Application for those flows.

Why Draft and Submit

• One pattern for full and partial data. Only partnerId and merchantName are required to create a Draft. Send everything you have today and add the rest later.

• Nothing reaches the signer until you say so. A Draft is never sent for signature until you call submit.

• Attachments before signature. Upload PDF documents while the application is a Draft.

• Safe to correct. Replace the stored data with PUT, or discard the Draft entirely.

• Format and completeness checks wait for submit. Draft saves do not apply format checks such as EIN or email format, so you can save incomplete data without errors.

The flow

1. Create the Draft. POST /merchant-onboarding/applications/drafts with the data you have inside merchantData. Store the returned applicationId.

2. Update the Draft as you collect more data (optional). PUT /merchant-onboarding/applications/drafts/{applicationId} with the full merchantData.

3. Attach documents (optional). POST /merchant-onboarding/applications/{applicationId}/attachments. See Application Attachments.

4. Submit. POST /merchant-onboarding/applications/{applicationId}/submit with no body. Bead sends the application to the signer.

5. Track progress. Poll Get Status, subscribe to webhooks, or both.

A typical status path looks like this:

draft → signing → signed → reviewing → reviewed → boarding → boarded

Endpoints

All endpoints use API key authentication with the X-Api-Key header.

Action	Endpoint	Notes
Create Draft	POST /merchant-onboarding/applications/drafts	Body is { "merchantData": { ... } }. Returns applicationId.
Update Draft	PUT /merchant-onboarding/applications/drafts/{applicationId}	Full replace of the stored data. Returns the updated application.
Discard Draft	DELETE /merchant-onboarding/applications/drafts/{applicationId}	Returns 204. Permanently deletes the Draft and its attachments.
Upload attachment	POST /merchant-onboarding/applications/{applicationId}/attachments	PDF only. Draft status only.
List attachments	GET /merchant-onboarding/applications/{applicationId}/attachments	Verify the package before submitting.
Delete attachment	DELETE /merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}	Draft status only.
Submit	POST /merchant-onboarding/applications/{applicationId}/submit	No request body. Draft status only.

PUT /merchant-onboarding/applications/drafts/{applicationId} updates a Draft. PUT /merchant-onboarding/applications/{applicationId} is a different endpoint that resends an application that is already in the signer facing flow. See Resend Application.

Request shape

The request body wraps all merchant fields in merchantData. The field names inside merchantData are the same names used by POST /merchant-onboarding/applications, including feeInformation, stakeholders, and cryptoEnvironment.

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

Required fields

Field	Description
merchantData.partnerId	Your Bead partner identifier.
merchantData.merchantName	The merchant name.

Every other field is optional when you save a Draft.

Strict field names

Draft requests reject unknown properties with a 400. This applies to the request wrapper, to merchantData, and to each stakeholder. For example, a flat body with partnerId at the top level fails with 'partnerId' is not a recognized property. Always nest merchant fields inside merchantData, and use the exact field names shown in the full sample below.

Field notes

• Addresses use address1, address2, city, region, country, and postalCode.

• The point of contact uses phoneNumber, and so do stakeholders.

• submitImmediately is not accepted on Draft requests. You control timing by calling submit.

• Send at most 5 stakeholders, with at most one marked isApplicationSigner: true.

• feeInformation is optional on a Draft, but when you include it, it is validated. See Fee Configuration for Onboarding Applications.

• Set exactly one of isLegalAddress, isOperatingAddress, and isVirtualAddress to true. These flags drive the address type shown on the application. Send businessMailingAddress when isOperatingAddress is true.

• sameAsRegisteredAddress is accepted but not stored. Send the address you want recorded in businessMailingAddress.

• hasNoOwners: true tells Bead that no individual owns 25 percent or more of the business.

Minimal sample

The smallest valid Draft contains only the two required fields.

curl --request POST \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/drafts \
  --header "X-Api-Key: {apiKey}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "merchantData": {
      "partnerId": "partner_123",
      "merchantName": "Northwind Coffee Roasters"
    }
  }'

Response:

{
  "applicationId": "app-123exampleid"
}

Store applicationId. Every later call on the application uses it. The envelopeId and status values are not populated until the application is submitted.

Full sample

This Draft carries a complete merchant profile with a signer, banking details, and fee information. Use it as the reference for field names and shapes.

{
  "merchantData": {
    "partnerId": "partner_123",
    "merchantName": "Northwind Coffee Roasters",
    "partnerExternalId": "ext-merchant-2048",
    "registeredName": "Northwind Coffee Roasters LLC",
    "dbaName": "Northwind Coffee Roasters",
    "federalTaxIdType": "ein",
    "federalTaxId": "123456789",
    "naicsCode": "722515",
    "merchantCategoryCode": "5499",
    "businessDescription": "Retail coffee roaster and cafe",
    "proofOfBusinessType": "businessLicense",
    "registrationDate": "2021-04-12",
    "legalEntityType": "llc",
    "grossAnnualRevenue": 1250000,
    "highestMonthlyVolume": 160000,
    "averageTicketSize": 32,
    "maxTicketSize": 500,
    "registeredLegalAddress": {
      "address1": "123 Harbor Street",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02110"
    },
    "proofOfAddressType": "utilityBill",
    "businessMailingAddress": {
      "address1": "123 Harbor Street",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02110"
    },
    "isLegalAddress": false,
    "isOperatingAddress": true,
    "isVirtualAddress": false,
    "locationBusinessType": "physical",
    "locationName": "Northwind Coffee Roasters",
    "businessWebsite": "https://northwind.example.com",
    "businessEmail": "[e-mail]",
    "businessPhone": "[phone]",
    "mainPointOfContact": {
      "firstName": "Morgan",
      "lastName": "Reed",
      "email": "[e-mail]",
      "phoneNumber": "[phone]"
    },
    "hasNoOwners": false,
    "stakeholders": [
      {
        "firstName": "Morgan",
        "lastName": "Reed",
        "dateOfBirth": "1987-06-15T00:00:00Z",
        "citizenship": "US",
        "ownershipPercentage": 100,
        "ownershipType": "direct",
        "idType": "passport",
        "idNumber": "123456789",
        "countryOfIssuance": "US",
        "taxIdType": "ssn",
        "taxIdNumber": "123456789",
        "proofOfIdentityType": "passport",
        "proofOfAddressType": "utilityBill",
        "address": {
          "address1": "123 Harbor Street",
          "city": "Boston",
          "region": "MA",
          "country": "US",
          "postalCode": "02110"
        },
        "email": "[e-mail]",
        "phoneNumber": "[phone]",
        "jobTitle": "Owner",
        "isApplicationSigner": true
      }
    ],
    "bankName": "First Harbor Bank",
    "routingNumber": "011000015",
    "accountNumber": "1234567890",
    "accountType": "checking",
    "proofOfBankAccountType": "bankLetter",
    "bankDepositMethod": "ach",
    "bankAddress": {
      "address1": "10 Bank Plaza",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02111"
    },
    "feeInformation": {
      "achSettlementFixedFee": {
        "sellRate": 1.5,
        "isBilledByPartner": false
      },
      "settlementReturnFixedFee": {
        "sellRate": 15,
        "isBilledByPartner": false
      },
      "monthlyMaintenanceFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      },
      "bitcoinFee": {
        "transactionRate": {
          "sellRate": 2.5,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.25,
          "isBilledByPartner": false
        }
      },
      "stablecoinFee": {
        "transactionRate": {
          "sellRate": 2.5,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0.25,
          "isBilledByPartner": false
        }
      },
      "digitalWalletsFees": [
        {
          "tenderType": "paypal",
          "paymentLocationType": "inStore",
          "transactionRate": {
            "sellRate": 2.29,
            "isBilledByPartner": false
          },
          "perItemFee": {
            "sellRate": 0.09,
            "isBilledByPartner": false
          },
          "refundFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          },
          "chargebackFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          }
        },
        {
          "tenderType": "paypal",
          "paymentLocationType": "online",
          "transactionRate": {
            "sellRate": 3.6,
            "isBilledByPartner": false
          },
          "perItemFee": {
            "sellRate": 0.49,
            "isBilledByPartner": false
          },
          "refundFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          },
          "chargebackFee": {
            "sellRate": 0,
            "isBilledByPartner": false
          }
        }
      ]
    },
    "cryptoEnvironment": "sandbox"
  }
}

The sample prices PayPal only. For each additional wallet or BNPL tender you price, add an inStore row and an online row in the same shape. See Sample Payload for the complete fee reference.

Send it:

curl --request POST \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/drafts \
  --header "X-Api-Key: {apiKey}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data @northwind-draft.json

Update a Draft

Send the complete merchantData again to replace what is stored. This is a full replace, not a merge, so any field you leave out is cleared.

The request body is identical to Create a Draft. applicationId appears only in the URL.

curl --request PUT \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/drafts/app-123exampleid \
  --header "X-Api-Key: {apiKey}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data @northwind-draft-updated.json

The response is the updated application. The same strict field name rules apply as on create.

Attach documents

Attachments are PDF only and can be added or deleted only while the application is a Draft. Upload each file with a category, and include stakeholderIndex for stakeholder documents.

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

See Application Attachments for categories, size limits, and examples.

Submit

When the Draft is ready, submit it. The request has no body.

curl --request POST \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/app-123exampleid/submit \
  --header "X-Api-Key: {apiKey}" \
  --header "Accept: application/json"

Response:

{
  "applicationId": "app-123exampleid",
  "envelopeId": "env-1111-2222-3333-4444",
  "status": "signing"
}

envelopeId is an internal signing reference. You do not need it for any Bead API call.

What submit checks

Submit is where completeness is enforced. The request is rejected if any of these are not met:

• the application is in Draft status

• one stakeholder is marked isApplicationSigner: true

• attachments, where provided, are PDF files

• each stakeholder has a date of birth

• fee information is complete, including the ACH settlement fixed fee and the settlement return fixed fee

• fees meet the fee group and partner sell rate checks configured for your partner

• the signer email is unique

If submit fails, fix the data with PUT, then submit again. The Draft stays in Draft status until a submit succeeds.

Remaining fields are completed by the signer

Any application fields still blank at submit can be completed by the signer in Bead's hosted signing experience. Send as much as you have so the signer mainly reviews, confirms, and signs.

Discard a Draft

Discard a Draft that is no longer needed.

curl --request DELETE \
  --url https://api.test.devs.beadpay.io/merchant-onboarding/applications/drafts/app-123exampleid \
  --header "X-Api-Key: {apiKey}"

A successful discard returns 204 No Content and permanently deletes the Draft and its attachments. Discard works only on Draft applications. Calling it on any other status returns 400 with the message Only Draft applications can be discarded. To stop an application that has left Draft status, see Cancel Application.

Error handling

Scenario	Result
Missing partnerId or merchantName	400 validation error.
Unknown property in the wrapper, merchantData, or a stakeholder	400, for example 'partnerId' is not a recognized property.
More than 5 stakeholders, or more than one signer	400 validation error.
feeInformation present but invalid	400 validation error.
Submit on an application that is not a Draft	Request rejected.
Submit with missing signer, dates of birth, or fee information	Request rejected with the failing check.
Discard on a non Draft application	400, Only Draft applications can be discarded.
Unknown applicationId	404 Not Found.
Missing or invalid API key	401 Unauthorized.

Best practices

• Start with Draft and Submit for every new integration.

• Save a Draft as soon as you have a merchant name, then enrich it as data arrives.

• Always nest merchant fields in merchantData and use the exact field names from the full sample.

• Resend the complete merchantData on every PUT.

• Mark one stakeholder as the signer before you submit.

• Upload and list attachments before you submit, because they cannot change afterward.

• Store applicationId immediately after create.

• Discard abandoned Drafts so your records stay clean.

• Use GET /merchant-onboarding/applications/{applicationId} and webhooks to track the application after submit.

Related pages

• Submit Application

• Sample Payload

• Application Attachments

• Fee Configuration for Onboarding Applications

• Get Status

• Resend Application

• Cancel Application

• Webhooks for Application Events

• Test the Full Onboarding Workflow in Sandbox