Common Field Types

These field types and shared objects are reused across Bead APIs. Use these definitions to validate input and normalize data handling in your integration.

Address

Standardized address object used for merchants, owners, locations, and bank accounts.

Field	Type	Required	Notes
address1	string	Yes	Primary street address
address2	string	No	Secondary street address such as apartment or suite
city	string	Yes	City or locality
region	string	Yes	State, province, or region
postalCode	string	Yes	Postal or ZIP code
country	string	Yes	ISO 3166-1 alpha-2 code such as US

Boolean Flags

Flags commonly used across entities.

Field	Type	Description
isEnabled	boolean	Marks entity active or inactive
displayLogo	boolean	Show or hide merchant logo in hosted UI
isSeasonal	boolean	Business operates seasonally
sameAsRegisteredAddress	boolean	Business mailing address equals legal address

Primitive Field Types

Field Type	Format or Pattern	Example	Notes
Email	string, RFC 5322	[email protected]	Must be a valid address
Phone	string, E.164 recommended	[phone]	Digits only also accepted
Currency Code	string ISO 4217	USD, EUR	Standard currency codes
Amount	number decimal	100.00	Base units of the currency
Date	string YYYY-MM-DD	2025-03-21	Calendar date
Date Time	string ISO 8601	2025-03-21T14:30:00Z	UTC unless noted otherwise
Boolean	true or false	true	JSON boolean
Postal Code	string	02116	Country specific formats allowed
Region	string	MA	State, province, or subdivision
Country	string ISO 3166-1 alpha-2	US, CA, GB	Two character code
Tax ID	string 9 digits	123456789	EIN, SSN, or ITIN by context
Percent	number 0 to 100	25	Ownership or rate values

Error Object

Standard error envelope returned by APIs when a request fails.

Field	Type	Required	Description
error	string	Yes	Machine readable type such as InvalidRequest, Conflict, ServerError
message	string	Yes	Human readable description of the problem
fieldErrors	array of objects	No	Per field validation issues see below
requestId	string	No	Identifier for support and log correlation
status	integer	No	HTTP status code repeated for convenience

fieldErrors item

Field	Type	Description
field	string	Field path such as business.legalName, owners[0].ssn
message	string	Reason the field failed validation

Examples

400 Bad Request

{
  "error": "InvalidRequest",
  "message": "business.legalName is required",
  "fieldErrors": [
    { "field": "business.legalName", "message": "This field is required." }
  ],
  "requestId": "req_8a1f3c"
}

409 Conflict

{
  "error": "Conflict",
  "message": "An application already exists for this taxId",
  "requestId": "req_d2b9e7"
}

500 Internal Server Error

{
  "error": "ServerError",
  "message": "An unexpected error occurred. Please try again later.",
  "requestId": "req_c41aa0"
}

Usage Notes

• These definitions are referenced throughout Onboarding, Merchant, Location, Terminal, and Payment APIs.

• Validate formats client side where possible to avoid 400 series errors.

• Treat enums such as TaxIdType or ProofOfAddressType as open ended. New values may appear over time. Unknown values should raise a clear error in your integration.