> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests & Responses

> Required headers, data formats, dates, identifiers and metadata, pagination, and other conventions for Platform API requests and responses.

These requirements and formats apply to every Platform API request and response.

## Headers

| Header | Required for | Value |
| :- | :- | :- |
| `Authorization` | All requests | `Basic` followed by the Base64 encoding of `client_id:api_key`, or `Bearer` for a few processor endpoints. See [Authentication & Security](./authentication-and-security). |
| `Accept` | All requests | `application/json` |
| `Accept-Version` | All requests | The API version, for example `v20260929`. See [Specify a version](./versioning#specify-a-version). |
| `Content-Type` | `POST` and `PUT` requests | `application/json` |

<Note>
  The legacy header `Accept: application/vnd.mx.api.v1+json` still works and requests v20111101. Move to `Accept: application/json` with an `Accept-Version` header.
</Note>

## Data format

Requests and responses use JSON, including error responses (see [Errors](./errors)). The exceptions are:

* Download Statement PDF returns a PDF file.
* Some responses, such as `204 No Content`, have no body.
* Encrypted responses return an encrypted JWE string.

Requests must use UTF-8 character encoding.

## Request bodies

`PUT` request bodies can't be empty. Include at least one parameter inside the body's root object, even when no parameter is required. An empty `PUT` body returns `400 Bad Request`.

## Boolean fields

Boolean fields accept only `true` or `false`. Don't use `0` or `1`.

## Dates and times

Dates and times use ISO 8601 format:

* Fields that end in `_on` are dates without a time, for example `2018-07-18`.
* Fields that end in `_at` are dates with a time and UTC offset, for example `2025-02-13T18:08:00+00:00`.

In v20250224 only, the date filters on List Transactions endpoints use Unix timestamps. See the [Upgrade Guide](./upgrade-guide#list-transactions-date-filters).

## Numbers

Some fields, such as account balances, have limits on decimal numbers, given as precision and scale (for example, `14,2`). Precision is the total number of digits, and scale is the number of digits to the right of the decimal point. For example, `538.46` has a precision and scale of `5,2`.

## Identifiers and metadata

<Warning>
  Don't store sensitive information in `metadata`, such as usernames, passwords, or account numbers.
</Warning>

Many resources you create through the API accept an optional `id` and an optional `metadata` field.

* **`id`:** Your own unique identifier for the resource. Use it to make sure a resource is created only once, or to match MX data with data on your platform. Creating a resource with an `id` that already exists returns `409 Conflict`.
* **`metadata`:** A string you can use to store additional data about the resource, such as a JSON-encoded string. MX doesn't use it.

## Pagination

Endpoints that return lists are paginated. Use these query parameters to control which page you get and how many records it contains:

| Parameter | Description |
| :- | :- |
| `page` | The page to return. Defaults to `1`. |
| `records_per_page` | The number of records per page. Defaults to `25`, and the minimum is `10`. The maximum varies by endpoint; see the endpoint's page for its range. If the value is outside the allowed range, the default of `25` is used. |

Each list response includes a `pagination` object:

```json theme={null}
"pagination": {
  "current_page": 1,
  "per_page": 25,
  "total_entries": 2,
  "total_pages": 1
}
```

| Field | Description |
| :- | :- |
| `current_page` | The page returned in this response. |
| `per_page` | The number of records on each page. |
| `total_entries` | The total number of records available. |
| `total_pages` | The total number of pages available. |

## Special characters in responses

Because of the financial nature of the data, string fields may contain special characters such as `'`, `<`, `>`, `"`, and `=`. For example, an account might be named `Mortgage Loan <= 15 Years`. Sanitize or encode API output before you display it, for example by HTML-encoding it before rendering it in a web view.

## Caching

Some resources, such as institutions, can change at any time. Avoid caching lists of these resources. If you need to cache them, refresh the cache at least once a day.