Submit Application

Use this page to create a new merchant onboarding application through the API.

You can submit either:

• a full application with most merchant data prefilled

• a minimal or empty application that Bead turns into a hosted onboarding package for the merchant signer to complete

Use the signerInfo object for signer details.

Choosing a flow

Use POST /merchant-onboarding/applications when:

• you already have most of the merchant’s business, ownership, banking, and fee information

• you want to prefill the application as much as possible

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

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

• you want to create a lighter-weight onboarding entry point

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

• you still want to provide signer and fee information up front

For both flows:

• use signerInfo for signer details

• provide required fee configuration

• 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

Full application

Use the full application flow when you want to submit a more complete onboarding request from your own system.

Endpoint

POST /merchant-onboarding/applications

When this flow fits best

Use the full application flow when:

• your system already has merchant onboarding data

• you want to reduce how much the merchant signer needs to enter manually

• you want tighter control over the submitted application payload

What to include

A full application typically includes:

• merchant identity and business details

• contact information

• ownership and stakeholder details

• banking and settlement information

• fee configuration

• signerInfo

Example request

{
  "partnerExternalId": "ext-merchant-2048",
  "signerInfo": {
    "name": "Morgan Reed",
    "email": "[email protected]",
    "position": "Owner"
  },
  "merchantData": {
    "registeredName": "Northwind Coffee Roasters LLC",
    "dbaName": "Northwind Coffee Roasters",
    "legalEntityType": "llc",
    "federalTaxIdType": "ein",
    "federalTaxId": "12-3456789",
    "businessDescription": "Retail coffee roaster and cafe"
  },
  "feeInformation": {
    "achSettlementFixedFee": {
      "sellRate": 1.5,
      "isBilledByPartner": false
    }
  }
}

This is an illustrative example only. Refer to the OpenAPI spec and schema definitions for the complete request model and required fields.

Minimal or empty application

Use the minimal or empty application flow when you want to create the application shell and let the hosted onboarding flow collect most of the remaining merchant information.

Endpoint

POST /merchant-onboarding/applications-short

When this flow fits best

Use the minimal flow when:

• you do not want to collect full onboarding data in your own system

• you want to get the merchant signer into the hosted flow quickly

• you only want to provide the minimum data needed to start the onboarding process

What to include

A minimal application typically includes:

• partner or merchant reference information

• signerInfo

• fee configuration

Example request

{
  "partnerExternalId": "ext-merchant-2048",
  "signerInfo": {
    "name": "Morgan Reed",
    "email": "[email protected]",
    "position": "Owner"
  },
  "feeInformation": {
    "achSettlementFixedFee": {
      "sellRate": 1.5,
      "isBilledByPartner": false
    }
  }
}

This is an illustrative example only. Refer to the OpenAPI spec and schema definitions for the complete request model and required fields.

What happens next

After you submit either type of application:

1. Bead creates the onboarding application record.

2. Bead sends the onboarding package to the merchant signer using the details in signerInfo.

3. The merchant signer completes the hosted onboarding flow.

4. You track progress using the application status endpoints and related onboarding pages.

Typical response fields

A successful response typically includes:

• applicationId

• envelopeId

• status

• signingUrl when available

Example response

{
  "applicationId": "app-123exampleid",
  "envelopeId": "env-1111-2222-3333-4444",
  "status": "sent",
  "signingUrl": "https://sign.example.com/session/abc123"
}

Store applicationId and envelopeId so you can track the application later.

Best practices

• Use the full application flow when you already have reliable merchant data.

• Use the minimal flow when you want the hosted experience to collect most data directly from the merchant signer.

• Treat signerInfo as the source of signer identity in your request.

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

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

Related pages

• Get Status

• Resend Application

• Webhooks for Application Events

• Sample Payload

• Reference Guide