> 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/reference-guide/enumerations-and-schemas/common-field-types.md). # Common Field Types Shared objects and field conventions used across the API. Use these definitions when building requests and interpreting responses. #### Address object | Field | Type | Required | Notes | | ------------ | ------ | -------- | ------------------------------ | | `address1` | string | Yes | Street line one | | `address2` | string | No | Suite or unit | | `city` | string | Yes | City or locality | | `region` | string | Yes | State or province such as `MA` | | `country` | string | Yes | ISO alpha two such as `US` | | `postalCode` | string | Yes | ZIP or postal code | **Example** ```json { "address1": "123 Main St", "address2": "Suite 200", "city": "Springfield", "region": "MA", "country": "US", "postalCode": "01109" } ``` #### Contact fields | Field | Type | Required | Notes | | -------------- | -------------- | ------------------- | ----------------------------------------------------------- | | `contactPhone` | string | Yes when documented | Local format or E.164 accepted. Prefer E.164 for production | | `contactEmail` | string | Yes when documented | Valid email address for notifications or support | | `website` | string or null | Conditional | Required when business type is `virtual`. Must be HTTPS | #### Identifiers Treat all identifiers as opaque strings. Preserve case and do not parse by prefix. | Entity | Example format | | -------- | --------------- | | Partner | `par_9f2a1cde` | | Merchant | `mer_4e5a13aa` | | Location | `loc_bfdc6a7f` | | Terminal | `term_12345678` | | Payment | `pay_abcdef12` | #### Monetary amounts and volumes Numeric values are JSON numbers. Do not quote numeric fields. | Field | Type | Meaning | | ---------------------- | -------------- | ----------------------------------------- | | `averageTicketSize` | number | Typical transaction amount for the entity | | `maxTicketSize` | number | Maximum expected transaction amount | | `highestMonthlyVolume` | number or null | Peak expected monthly volume if available | | `grossAnnualRevenue` | number | Estimated annual processing volume | Precision is two decimal places unless a field specifies otherwise. Currency is implied by the merchant or settlement rail unless a currency code is explicitly documented on that endpoint. #### Merchant category codes | Field | Type | Required | Notes | | -------------------------------- | -------------- | -------- | ------------------------------ | | `merchantCategoryCode` | string | Yes | Four digit MCC such as `5812` | | `additionalMerchantCategoryCode` | string or null | No | Additional MCC when applicable | Provide MCC values as strings to preserve leading zeros where used. #### Tender types Use the exact strings shown on the Tender Types pages. Values are case sensitive. | Example values | Notes | | -------------- | ----------------------- | | `usdcBase` | USDC on Base network | | `ethereum` | ETH on Ethereum network | When a location or terminal omits `tenderTypes`, defaults from the parent are applied according to the entity documentation. #### Timestamps | Topic | Convention | | -------- | -------------------------------------------------- | | Format | ISO 8601 in UTC with `Z` suffix | | Examples | `2025-09-02T16:22:11Z`, `2025-09-02T16:22:11.015Z` | | Fields | `created` and `updated` use UTC consistently | #### Pagination parameters and envelope Paginated endpoints accept common parameters and return a standard envelope. | Name | Type | Required | Notes | | ---------- | ------- | -------- | --------------------------------------------------- | | `page` | integer | No | One based page number with a default of one | | `pageSize` | integer | No | Items per page with a sensible default per endpoint | **Response envelope** | Field | Type | Notes | | ------- | ------- | ---------------------------------------- | | `data` | array | Results for the requested page | | `total` | integer | Total number of records across all pages | | `page` | integer | Page number that was returned | Some list endpoints return a bare array when the full set is expected to be small. Those endpoints do not use pagination parameters or the envelope. #### Error object All error responses follow a consistent JSON shape. Surface `message` to users and log `traceId` for support. ```json { "code": "validation_error", "error": "Invalid request", "message": "One or more fields are invalid.", "traceId": "00-73fffe343fd1d5b150beddb00730bb24-f182c31fd104b782-00", "details": [ { "field": "address.postalCode", "message": "Invalid format" } ] } ``` | Field | Type | Description | | --------- | ------ | ----------------------------------------------------------------------------- | | `code` | string | Stable programmatic code such as `validation_error`, `not_found`, `forbidden` | | `error` | string | Short category label used in logs | | `message` | string | Human readable explanation | | `traceId` | string | Correlation identifier for support | | `details` | array | Optional per field errors with `field` and `message` | #### Header conventions Most Bead APIs use an API key sent in the `X-Api-Key` header. Some legacy or specialized endpoint families use OAuth 2.0 Bearer tokens. Use the authentication method documented for the specific product area you are integrating with. | Header | Value | When | | --------------- | ----------------------- | ------------------------------------------------- | | `X-Api-Key` | `{apiKey}` | Payments, Onboarding, and most other API families | | `Authorization` | `Bearer ` | Endpoint families that explicitly require OAuth | | `Content-Type` | `application/json` | Requests with a JSON body | | `Accept` | `application/json` | All requests | #### URL and webhook fields | Field | Requirements | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | Used for callback and webhook style fields such as `PUT /Terminals/{terminalId}/webhook`. Must be a fully qualified `https` URL that is routable from Bead. Use a stable hostname (no `localhost` in production) and keep the path stable so you can rotate secrets without changing the URL. | | `webhookUrls` | Array of URL strings used for per payment overrides on `POST /payments/crypto`. Each entry must meet the same requirements as `url`. Be prepared to receive the same event at both the terminal level URL and every URL listed in `webhookUrls`. | --- # 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/reference-guide/enumerations-and-schemas/common-field-types.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.