# 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.

```http
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:

```http
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

```http
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.

{% code expandable="true" %}

```json
{
  "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": "ops@northwind.example.com",
    "businessPhone": "+15085550100",
    "mainPointOfContact": {
      "firstName": "Morgan",
      "lastName": "Reed",
      "email": "morgan.reed@example.com",
      "phoneNumber": "+15085550101"
    },
    "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": "morgan.reed@example.com",
        "phoneNumber": "+15085550101",
        "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"
  }
}
```

{% endcode %}

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.

```json
{
  "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": "morgan.reed@example.com",
        "phoneNumber": "+15085550101",
        "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.

```http
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:

```http
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

```http
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

```json
{
  "merchantName": "Northwind Coffee Roasters",
  "partnerId": "partner_123",
  "partnerMid": "northwind-2048",
  "signerFirstName": "Morgan",
  "signerLastName": "Reed",
  "signerEmail": "morgan.reed@example.com",
  "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

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

```json
{
  "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 `+15085550100` where applicable.

#### Related pages

* [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md)
* [Application Attachments](/onboarding/application-attachments.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)
* [Test the Full Onboarding Workflow in Sandbox](/onboarding/test-the-full-onboarding-workflow-in-sandbox.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/submit-application.md?ask=<question>
```

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.