Submit Application

Create a new merchant onboarding application through the API.

Two submission patterns are available:

• a full application with merchant data prefilled in your request

• a short application that starts the onboarding process with a smaller payload and lets the hosted onboarding flow collect the remaining information

By default, Bead creates the application and immediately sends it to the signer. If you need to upload supporting documents before the signer receives the application, set submitImmediately to false so the application is created in Draft status.

For the full application flow, identify the signer inside merchantData.stakeholders by setting isApplicationSigner to true.

For the short application flow, send signer details using signerFirstName, signerLastName, and signerEmail.

Choosing a flow

Choose POST /merchant-onboarding/applications when:

• your system already has merchant business, ownership, banking, and fee information

• you want to prefill the onboarding package as much as possible

• you want the signer to mainly review, confirm, and sign

• you may need to create the application in Draft status and upload attachments before sending it to the signer

Choose POST /merchant-onboarding/applications-short when:

• you want a lighter-weight entry point

• you want the hosted onboarding flow to collect most of the remaining merchant information

• you still want to provide signer details, fee information, and crypto environment up front

For both flows:

• provide the required fee configuration

• set cryptoEnvironment correctly for the environment you are using

• decide whether to submit immediately or create the application in Draft status

• store the returned applicationId and envelopeId

Authentication and headers

Onboarding requests use API key authentication.

X-Api-Key: {apiKey}
Content-Type: application/json
Accept: application/json

Submit behavior

Use submitImmediately to control whether Bead sends the application to the signer immediately or creates it in Draft status.

Value	Behavior
omitted	Bead preserves the existing default behavior and sends the application to the signer immediately.
true	Bead creates the application and immediately starts the signer flow.
false	Bead creates the application in Draft status so attachments can be uploaded before the signer receives it.

Use submitImmediately: false when you need to upload supporting documents through the attachment endpoints before sending the application for signature.

After all required attachments have been uploaded, call:

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

This submits the Draft application for signature and starts the DocuSign signing flow. The latest OpenAPI includes this dedicated Draft submit endpoint, separate from the resend/resubmit endpoint.

Full application

The full application flow is designed for partners that want to submit a more complete onboarding request from their own system.

Endpoint

POST /merchant-onboarding/applications

Signer guidance

For the full application flow, the signer is identified in merchantData.stakeholders.

Set isApplicationSigner to true for the stakeholder who should receive and sign the application.

Only one stakeholder should be designated as the application signer.

What to include

A full application typically includes:

• merchant identity and business details in merchantData

• contact and point-of-contact information

• stakeholder and ownership details

• banking and settlement details

• fee configuration

• crypto environment

• submitImmediately when you want to explicitly control Draft vs. immediate-send behavior

Example: submit immediately

This example shows the default one-step flow. Bead creates the application and sends it to the signer.

{
  "submitImmediately": true,
  "merchantData": {
    "merchantName": "Northwind Coffee Roasters",
    "partnerId": "partner_123",
    "partnerExternalId": "ext-merchant-2048",
    "registeredName": "Northwind Coffee Roasters LLC",
    "dbaName": "Northwind Coffee Roasters",
    "federalTaxIdType": "ein",
    "federalTaxId": "123456789",
    "merchantCategoryCode": "5499",
    "businessDescription": "Retail coffee roaster and cafe",
    "registeredLegalAddress": {
      "address1": "123 Harbor Street",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02110"
    },
    "businessMailingAddress": {
      "address1": "123 Harbor Street",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02110"
    },
    "isLegalAddress": true,
    "isOperatingAddress": true,
    "isVirtualAddress": false,
    "locationName": "Northwind Coffee Roasters",
    "businessWebsite": "https://northwind.example.com",
    "businessEmail": "[email protected]",
    "businessPhone": "[phone]",
    "mainPointOfContact": {
      "firstName": "Morgan",
      "lastName": "Reed",
      "email": "[email protected]",
      "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": "[email protected]",
        "phoneNumber": "[phone]",
        "jobTitle": "Owner",
        "isApplicationSigner": true
      }
    ],
    "bankName": "First Harbor Bank",
    "routingNumber": "011000015",
    "accountNumber": "1234567890",
    "accountType": "checking",
    "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
      }
    },
    "cryptoEnvironment": "sandbox"
  }
}

You can omit submitImmediately when you want the default immediate-send behavior.

Example: create Draft application for attachments

Use this pattern when you need to upload documents before the signer receives the application.

{
  "submitImmediately": false,
  "merchantData": {
    "merchantName": "Northwind Coffee Roasters",
    "partnerId": "partner_123",
    "partnerExternalId": "ext-merchant-2048",
    "registeredName": "Northwind Coffee Roasters LLC",
    "dbaName": "Northwind Coffee Roasters",
    "federalTaxIdType": "ein",
    "federalTaxId": "123456789",
    "merchantCategoryCode": "5499",
    "businessDescription": "Retail coffee roaster and cafe",
    "stakeholders": [
      {
        "firstName": "Morgan",
        "lastName": "Reed",
        "email": "[email protected]",
        "phoneNumber": "[phone]",
        "jobTitle": "Owner",
        "ownershipPercentage": 100,
        "ownershipType": "direct",
        "dateOfBirth": "1987-06-15T00:00:00Z",
        "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
      }
    },
    "cryptoEnvironment": "sandbox"
  }
}

After creating the Draft application, upload attachments while the application is still in Draft status.

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

Then submit the Draft application for signature:

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

Attachments can only be added while the application is in Draft status, and deleting attachments is also limited to Draft applications.

Short application

The short application flow is designed for partners that want to start onboarding quickly and let the hosted onboarding flow collect most of the remaining merchant information.

Endpoint

POST /merchant-onboarding/applications-short

Signer guidance

For the short application flow, send signer details as top-level fields:

• signerFirstName

• signerLastName

• signerEmail

What to include

A short application typically includes:

• merchantName

• partnerId

• partnerMid

• signer first name, last name, and email

• feeInformation

• cryptoEnvironment

• submitImmediately

Example request

{
  "merchantName": "Northwind Coffee Roasters",
  "partnerId": "partner_123",
  "partnerMid": "northwind-2048",
  "signerFirstName": "Morgan",
  "signerLastName": "Reed",
  "signerEmail": "[email protected]",
  "submitImmediately": true,
  "feeInformation": {
    "achSettlementFixedFee": {
      "sellRate": 1.5,
      "isBilledByPartner": false
    },
    "settlementReturnFixedFee": {
      "sellRate": 15,
      "isBilledByPartner": false
    },
    "monthlyMaintenanceFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    }
  },
  "cryptoEnvironment": "sandbox"
}

What happens next

If submitImmediately is omitted or set to true:

1. Bead creates the onboarding application record.

2. Bead creates the related signing package.

3. Bead sends the package to the signer.

4. The signer completes the hosted onboarding flow.

5. You track progress using the status endpoints and application event webhooks.

If submitImmediately is set to false:

1. Bead creates the onboarding application record in Draft status.

2. You upload any required attachments.

3. You optionally list or download attachments to verify the package.

4. You submit the Draft application using POST /merchant-onboarding/applications/{applicationId}/submit.

5. Bead sends the package to the signer.

6. You track progress using the status endpoints and application event webhooks.

Typical response fields

A successful response includes:

• applicationId

• envelopeId

• status

Store applicationId and envelopeId so you can track, submit, resend, or troubleshoot the application later.

Example response

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

For applications submitted immediately, the returned status may reflect the sent or signing state.

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

Best practices

• Choose the full application flow when you already have reliable onboarding data.

• Choose the short application flow when you want the hosted onboarding experience to collect most of the remaining data.

• For the full application flow, mark one stakeholder in merchantData.stakeholders with isApplicationSigner: true.

• Use submitImmediately: false when you need to upload attachments before the signer receives the application.

• Upload and verify all required attachments before calling POST /merchant-onboarding/applications/{applicationId}/submit.

• Keep fee configuration aligned with your commercial agreement before submitting the application.

• Store the returned identifiers so you can support submit, resend, status, webhook, and support workflows.

• Use international phone formatting such as [phone] where applicable.

Related pages

• Fee Configuration for Onboarding Applications

• Application Attachments

• Get Status

• Resend Application

• Webhooks for Application Events

• Sample Payload

• Test the Full Onboarding Workflow in Sandbox