> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/onboarding/field-validation-rules.md). # Field Validation Rules Before a submitted merchant onboarding application reaches a Bead reviewer, it is run through a set of automated field-level checks. These are the same checks Bead's own review tooling runs internally — validating your payload against them before submission catches the most common causes of review delay before they ever reach us. This page documents every rule currently enforced, grouped by category. Each rule lists what it checks, why it exists, and how to fix a failure. > **Tip:** Most failures on this list are cheap to catch client-side with a regex or a lookup table. If you're building an integration against the Onboarding API, we recommend running these checks against your payload before calling `POST /merchant-onboarding/applications` or `POST /merchant-onboarding/applications-short`. #### How to read this page Each rule below maps to a specific field or field pattern in the [Merchant Onboarding Schema](/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md). Fields are referenced using their path in the request payload, for example `merchantData.stakeholders[].phoneNumber`. ### Phone numbers **Phone number can normalize to E.164** Every phone number field must be cleanly convertible to E.164 format (`+15551234567`). * **Applies to:** `mainPointOfContact.phoneNumber`, `stakeholders[].phoneNumber`, `businessPhone`, `signerPhone` (short application) * **Fix:** Strip formatting characters and confirm the number resolves to a valid `+`-prefixed E.164 string before sending. **Phone number can convert from E.164 to E.123** Every phone number field must convert from its normalized E.164 form into the downstream E.123 international format (`+1 480 332 1255`). * **Applies to:** Same fields as above. * **Fix:** This is a downstream consequence of the E.164 check — if a number passes E.164 normalization but fails E.123 conversion, it usually indicates an unusual or malformed national number. Re-verify the number with the merchant. **Phone number includes US country code** Phone numbers should include an explicit US country code (`+1`). * **Applies to:** Same fields as above. * **Fix:** Always send the leading `+1` rather than a bare 10-digit number. ### Contact formatting **Email is properly formatted** Every email field must be a valid, well-formed email address. * **Applies to:** `mainPointOfContact.email`, `stakeholders[].email`, `businessEmail`, `signerEmail` * **Fix:** Validate against a standard email regex or library before submission. Watch for trailing whitespace and copy-paste artifacts from CRM exports. **Website is properly formatted** Every website field must be a valid `http` or `https` URL. * **Applies to:** `businessWebsite` * **Fix:** Include the protocol (`https://…`). A bare domain without a scheme will fail. ### Identity and compliance **Date of birth is 10+ years old** Every stakeholder date of birth must be at least 10 years before today. * **Applies to:** `stakeholders[].dateOfBirth` * **Fix:** Confirm the date isn't transposed (day/month swap is the most common cause) and that it isn't accidentally defaulting to the current date. **SSN uses valid US ranges** An SSN used as a tax ID must be 9 digits, with: * area number not `000`, `666`, or in the `900`–`999` range * group number not `00` * serial number not `0000` * **Applies to:** `stakeholders[].taxIdNumber` when `taxIdType` is `ssn` * **Fix:** These ranges were never issued by the SSA and indicate placeholder, test, or transposed data. Confirm the value with the stakeholder rather than guessing a fix. Remember the field must also be exactly 9 digits with no dashes — see [Merchant Onboarding Schema](/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md). **Business EIN differs from stakeholder tax ID** The business `federalTaxId` (EIN) must not match any stakeholder's `taxIdNumber`. * **Applies to:** `federalTaxId` compared against every `stakeholders[].taxIdNumber` * **Fix:** This usually indicates the business EIN was copy-pasted into a stakeholder record, or vice versa. Confirm each identifier was pulled from the correct source field. ### Address **Street 1 or address 1 is populated** Every address object must include `address1` (or the equivalent street line) with more than 5 characters. * **Applies to:** `registeredLegalAddress`, `businessMailingAddress`, `stakeholders[].address`, `bankAddress` * **Fix:** A PO Box abbreviation or single-character placeholder will fail this check. Confirm a real street line is present. **Postal code has 5+ digits** Every address object must include a postal or zip code with at least 5 digits. * **Applies to:** Same address objects as above. * **Fix:** Confirm the field isn't truncated (e.g., a leading zero dropped by a spreadsheet import). **State is 2 characters** Every address object must include a 2-letter state or region code. * **Applies to:** `region` field on the same address objects. * **Fix:** Send USPS 2-letter abbreviations (`MA`, not `Massachusetts`). **Country is US only** Every address object must have `country` set to `US`. * **Applies to:** Same address objects as above. * **Fix:** Bead onboarding currently supports US-domiciled merchants only. Confirm `country` is the literal string `US`, not a full country name. **Citizenship and issuance country are US** Every stakeholder `citizenship` and `countryOfIssuance` field must be set to `US`. * **Applies to:** `stakeholders[].citizenship`, `stakeholders[].countryOfIssuance` * **Fix:** As with address country, this must be the ISO alpha-2 code `US`. ### Classification codes **NAICS is a current 2022 code** `naicsCode` must be a current 2022, 6-digit NAICS code. * **Applies to:** `naicsCode` * **Fix:** Legacy 2- or 4-digit NAICS codes (from older classification revisions) will fail. Look up the current 6-digit 2022 code for the merchant's business activity — the [U.S. Census NAICS lookup tool](https://www.census.gov/naics/) is the canonical source. This is the single most common validation failure seen in review. **MCC is 4 digits** `merchantCategoryCode` must be a valid 4-digit number and cannot be all zeros or all nines. * **Applies to:** `merchantCategoryCode`, `additionalMerchantCategoryCode` * **Fix:** Send as a string to preserve leading zeros (see [Common Field Types](/reference-guide/enumerations-and-schemas/common-field-types.md)), and confirm the value isn't a placeholder like `0000` or `9999`. ### Attachments **Attachments are PDF only** All application attachments must be PDF files. * **Applies to:** Files uploaded through the [Application Attachments](/onboarding/application-attachments.md) endpoints. * **Fix:** Convert scanned images or Office documents to PDF before upload. Other formats will be rejected at upload time or flagged in review. ### Pricing and tenders **Tender pricing has both percentage and transaction rates** Bitcoin and USDC pricing must be present, and each configured tender must include both a percentage fee rate and a transaction fee rate. * **Applies to:** `feeInformation.bitcoinFee`, `feeInformation.stablecoinFee` * **Fix:** Both `transactionRate` and `perItemFee` sub-objects are required for each configured tender — confirm neither was omitted when building `feeInformation`. See [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md). **Partner-enabled wallets have pricing configured** Any wallet tender enabled at the partner level must have a corresponding entry in `feeInformation.digitalWalletsFees`. This is a warning-level check, not a hard failure. * **Applies to:** `feeInformation.digitalWalletsFees` * **Fix:** Cross-check the merchant's enabled wallet tenders against your partner-level tender configuration and add any missing pricing entries. ### Settlement-only applications **Settlement-only applications omit disallowed revenue and ticket fields** When `isSettlementOnly` is `true`, the application must **not** include `grossAnnualRevenue`, `highestMonthlyVolume`, `averageTicketSize`, or `maxTicketSize`. * **Applies to:** `grossAnnualRevenue`, `highestMonthlyVolume`, `averageTicketSize`, `maxTicketSize` when `isSettlementOnly` is `true` * **Fix:** Omit these fields entirely from the payload for settlement-only merchants rather than sending zero or null values. ### Related pages * [Submit Application](/onboarding/submit-application.md) * [Merchant Onboarding Schema](/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md) * [Common Field Types](/reference-guide/enumerations-and-schemas/common-field-types.md) * [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md) * [Application Attachments](/onboarding/application-attachments.md) * [How do I resolve a 400 ValidationError?](/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-resolve-a-400-validationerror.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/onboarding/field-validation-rules.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.