Submit Application

Use the onboarding APIs to create merchant applications from your own systems. This page shows how to submit:

  • A full application with comprehensive merchant data

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

Both flows:

  • Require signer information so Bead knows who should receive and sign the application

  • Depend on fee configuration that is not editable in the hosted experience

After you submit an application, Bead sends a secure onboarding email to the signer. You track progress using Get Status and webhooks, and you can send the application back to the same signer using the resend endpoint.

Prerequisites

Before calling these endpoints:

  • Obtain an access token for the bead-integrator client

  • Have your partnerId and any partner-specific merchant identifiers you plan to send

  • Confirm how fee configuration is set for your program. Fees are not editable by the signer in the hosted experience and must be known up front.

  • Decide whether you will surface onboarding status in your own portal or rely primarily on internal tools

All onboarding endpoints require a valid OAuth access token.

Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

Full application

Use the full application flow when your system already has most of the merchant’s information and you want to prefill the application. The signer mostly reviews and confirms details.

Endpoint

The request body uses the InitiateOnboardingRequest model:

  • merchantData The full merchant onboarding payload, including business identity, addresses, ownership, banking, and feeInformation.

  • signer The person who will receive and sign the application.

Request body structure

At a high level, merchantData includes:

  • Core identifiers

    • merchantName

    • partnerId

    • partnerExternalId

    • partnerMid

  • Business and registration details

    • registeredName, dbaName

    • businessDescription

    • legalEntityType, otherLegalEntity

    • registrationDate

    • merchantCategoryCode, naicsCode, additionalMcc

  • Tax and entity information

    • federalTaxId, federalTaxIdType

  • Addresses and contacts

    • registeredLegalAddress

    • businessMailingAddress

    • mainPointOfContact

  • Volume and revenue profile

    • grossAnnualRevenue

    • highestMonthlyVolume

    • averageTicketSize

    • maxTicketSize

  • Seasonality

    • isSeasonalBusiness or isSeasonal

    • monthsOfOperation or operationalMonths

  • Banking details

    • bankName

    • routingNumber, accountNumber, accountType

    • bankDepositMethod

    • bankAddress

  • Documents

    • proofOfBankAccountType

    • proofOfBusinessType

    • proofOfLegalAddressType

    • Optional proof document locations, depending on stage and flow

  • Ownership and stakeholders

    • hasNoOwners

    • stakeholders with name, address, ownership percentage, identification and tax fields, and proof of identity and address values

  • Fees

    • feeInformation with settlement fees, crypto fees, and digital wallet fees

The signer object includes:

  • email

  • name

  • position

Bead uses this to send the onboarding email and record who signed the application.

Full application example

Use this as a reference and adjust fields to match your program. In particular, confirm which fields are required and any enumeration values for your environment in the API specification.

Minimal or “empty” application

Use the minimal application flow when you want to collect only basic identifiers and signer information up front and let the hosted onboarding experience collect most remaining data. You still must have fee configuration defined for the merchant because fees are not editable by the signer.

Endpoint

The request body uses the InitiateEmptyOnboardingRequest model with a smaller set of fields focused on identification and signer details.

Typical fields:

  • merchantName

  • partnerId

  • partnerMid or partnerExternalId depending on your program

  • signerName

  • signerEmail

The hosted flow will prompt the signer for business details, ownership, banking, and any required documents.

Minimal application example

Your program configuration must ensure that feeInformation is known for this merchant, even though it may not be present in this minimal request. The signer cannot change fees in the hosted experience.

Responses

Both submit endpoints return the same response model.

Example:

Fields:

  • applicationId Bead’s identifier for the onboarding application. Use this when calling Get Status, webhooks, and resend related operations.

  • envelopeId Identifier for the underlying signing envelope.

  • status Current status of the agreement envelope at the time of creation, for example sent.

Bead uses the signer information from your request to send the onboarding email. Treat email delivery as the primary path for the signer to enter the hosted onboarding flow.

Choosing a flow

Use this quick guide to decide which endpoint to call:

  • Use POST /merchant-onboarding/application when

    • You already collect full KYB data in your system.

    • You want the signer to mostly review and confirm the information provided.

    • You want to explicitly send feeInformation per merchant in the request body.

  • Use POST /merchant-onboarding/application-short when

    • You want a lighter initial integration.

    • You prefer the hosted onboarding experience to drive which details are required.

    • Fees are configured for the merchant outside this request body, through your program configuration with Bead.

After submitting an application, use Get Status to retrieve the current state across agreement, compliance, banking, and crypto services, use webhooks for event-driven updates, and use the resend endpoint to send an existing application back to the same signer when they need to correct or update information.

PreviousOnboardingNextGet Status

Last updated