# API conventions

> Field naming, money, timestamps, ids, coordinates, and pagination in the Maxmove API.

## Requests and responses

- JSON bodies with snake_case field names.
- Money as an integer amount in cents plus an ISO 4217 `currency`, for example `"amount_cents": 4890, "currency": "EUR"`.
- Timestamps in RFC 3339, UTC.
- Ids carry a prefix: `qt_` quotes, `del_` deliveries, `we_` webhook endpoints, `evt_` events.
- Addresses come with coordinates. Maxmove does not geocode; send the coordinates your address search returned.
- New fields can appear in responses at any time. Ignore fields you do not know.

## Pagination

`GET /v1/deliveries` returns up to `limit` entries (1 to 20, default 20), newest first, plus `next_page_token`. Pass it as `page_token` to read the next page; it is `null` on the last page.

```bash cURL
curl "https://api.maxmove.com/v1/deliveries?limit=20&page_token=$NEXT_PAGE_TOKEN" \
  -H "x-api-key: $MAXMOVE_KEY"
```

```ts Node.js
let pageToken: string | null = null;
do {
  const url = new URL('https://api.maxmove.com/v1/deliveries');
  url.searchParams.set('limit', '20');
  if (pageToken) url.searchParams.set('page_token', pageToken);

  const res = await fetch(url, { headers: { 'x-api-key': process.env.MAXMOVE_KEY! } });
  const page = await res.json();
  for (const delivery of page.deliveries) console.log(delivery.id, delivery.status);
  pageToken = page.next_page_token;
} while (pageToken);
```

```python Python
import os
import requests

page_token = None
while True:
    params = {"limit": 20}
    if page_token:
        params["page_token"] = page_token
    page = requests.get(
        "https://api.maxmove.com/v1/deliveries",
        headers={"x-api-key": os.environ["MAXMOVE_KEY"]},
        params=params,
    ).json()
    for delivery in page["deliveries"]:
        print(delivery["id"], delivery["status"])
    page_token = page["next_page_token"]
    if not page_token:
        break
```

An invalid `page_token` answers `400 invalid_page_token`.

## Versioning

The major version is part of the path (`/v1`). Within v1, Maxmove only makes additive changes. See [Versioning](https://maxmove.com/en/developers/docs/versioning).

---

Source: https://maxmove.com/en/developers/docs/concepts/conventions