> 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

## 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                             |
| ------------- | ------ | -------- | --------------------------------- |
| `address`     | string | Yes      | Street address, max length 512    |
| `address2`    | string | No       | Suite or unit, max length 512     |
| `city`        | string | Yes      | City or locality, max length 128  |
| `state`       | string | Yes      | State or province, max length 128 |
| `countryCode` | string | Yes      | ISO alpha-2, e.g. `US`            |
| `postalCode`  | string | Yes      | ZIP or postal code, max length 32 |

**Example**

```json
{
  "address": "123 Main St",
  "address2": "Suite 200",
  "city": "Springfield",
  "state": "MA",
  "countryCode": "US",
  "postalCode": "01109"
}
```

### Customer object

The `customer` object (`CustomerRequest`) is used on:

* `POST /Payments/crypto`
* `POST /PaymentPages/{id}/request-quote`
* `POST /PaymentPages/{id}/pending-transaction`

It's optional by default on both physical and virtual terminals, but becomes required when a specific tender requires it (for example, Klarna requires `customer` on both physical and virtual terminals) or when merchant configuration, risk review, or compliance flow requires it. See [Create Payment](/payments/create-payment.md) for terminal-type guidance.

**No partial objects.** If you include `customer`, all required fields below must be present. A partial `customer` object returns `400 Bad Request`. If your flow doesn't need customer details, omit `customer` entirely rather than sending it partially filled.

| Field         | Type             | Required | Notes                        |
| ------------- | ---------------- | -------- | ---------------------------- |
| `firstName`   | string           | Yes      | Max length 128               |
| `lastName`    | string           | Yes      | Max length 128               |
| `email`       | string           | Yes      | Email format, max length 128 |
| `address`     | string           | Yes      | Max length 512               |
| `city`        | string           | Yes      | Max length 128               |
| `state`       | string           | Yes      | Max length 128               |
| `postalCode`  | string           | Yes      | Max length 32                |
| `countryCode` | string           | Yes      | ISO alpha-2, e.g. `US`       |
| `address2`    | string, nullable | No       | Max length 512               |
| `phone`       | string, nullable | No       | Max length 32                |

**Example**

```json
{
  "customer": {
    "firstName": "Jordan",
    "lastName": "Reed",
    "email": "jordan.reed@example.com",
    "address": "456 Market St",
    "address2": "Suite 210",
    "city": "Chicago",
    "state": "IL",
    "postalCode": "60601",
    "countryCode": "US"
  }
}
```

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

<table><thead><tr><th width="140.5">Name</th><th width="124.5">Type</th><th width="95">Required</th><th>Notes</th></tr></thead><tbody><tr><td><code>page</code></td><td>integer</td><td>No</td><td>One based page number with a default of one</td></tr><tr><td><code>pageSize</code></td><td>integer</td><td>No</td><td>Items per page with a sensible default per endpoint</td></tr></tbody></table>

**Response envelope**

<table><thead><tr><th width="141">Field</th><th width="169.5">Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>data</code></td><td>array</td><td>Results for the requested page</td></tr><tr><td><code>total</code></td><td>integer</td><td>Total number of records across all pages</td></tr><tr><td><code>page</code></td><td>integer</td><td>Page number that was returned</td></tr></tbody></table>

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" }
  ]
}
```

<table><thead><tr><th width="167.5">Field</th><th width="183.5">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>code</code></td><td>string</td><td>Stable programmatic code such as <code>validation_error</code>, <code>not_found</code>, <code>forbidden</code></td></tr><tr><td><code>error</code></td><td>string</td><td>Short category label used in logs</td></tr><tr><td><code>message</code></td><td>string</td><td>Human readable explanation</td></tr><tr><td><code>traceId</code></td><td>string</td><td>Correlation identifier for support</td></tr><tr><td><code>details</code></td><td>array</td><td>Optional per field errors with <code>field</code> and <code>message</code></td></tr></tbody></table>

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

<table><thead><tr><th width="165.5">Header</th><th width="240.5">Value</th><th>When</th></tr></thead><tbody><tr><td><code>X-Api-Key</code></td><td><code>{apiKey}</code></td><td>Payments, Onboarding, and most other API families</td></tr><tr><td><code>Authorization</code></td><td><code>Bearer &#x3C;access_token></code></td><td>Endpoint families that explicitly require OAuth</td></tr><tr><td><code>Content-Type</code></td><td><code>application/json</code></td><td>Requests with a JSON body</td></tr><tr><td><code>Accept</code></td><td><code>application/json</code></td><td>All requests</td></tr></tbody></table>

### URL and webhook fields

<table><thead><tr><th width="176">Field</th><th>Requirements</th></tr></thead><tbody><tr><td><code>url</code></td><td>Used for callback and webhook style fields such as <code>PUT /Terminals/{terminalId}/webhook</code>. 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.</td></tr><tr><td><code>webhookUrls</code></td><td>Array of URL strings used for per payment overrides on <code>POST /payments/crypto</code>. Each entry must meet the same requirements as <code>url</code>. Be prepared to receive the same event at both the terminal level URL and every URL listed in <code>webhookUrls</code>.</td></tr></tbody></table>


---

# 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=<question>&goal=<endgoal>
```

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