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

# API Conventions

> Idempotency, pagination, and versioning rules that apply to every Venly API endpoint.

These conventions apply uniformly across the **Fundflow API** and **Finance API**. Endpoint references link here rather than restating the rules — bookmark this page.

***

## Idempotency

State-changing endpoints (`POST` requests that create a resource) accept an `idempotencyKey` field in the request **body**. It is not a header.

```json theme={null}
{
  "idempotencyKey": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "amount": 100.00,
  "currency": "EUR",
  "...": "other fields"
}
```

Use a fresh UUID v4 for every new business operation. Reuse the **same** key only when retrying the **same** request.

### Behaviour

| You send                        | You get                                                   |
| ------------------------------- | --------------------------------------------------------- |
| A key for the first time        | The operation runs                                        |
| The same key with the same body | The original response, returned again — never a duplicate |

### When to use

| Required                                                   | Optional                    | Not applicable                                                               |
| ---------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------- |
| Transfers (fiat / crypto / A2A)                            | Most other `POST` endpoints | `GET` requests (already idempotent)                                          |
| Payment requests — create, settle, reverse, **and update** |                             | `PATCH` on parties/accounts (use the `version` field for optimistic locking) |
| Virtual bank account creation                              |                             | `DELETE` requests                                                            |
| Fiat-to-crypto payment sessions                            |                             |                                                                              |

<Tip>
  **Store the key client-side until you receive a `2xx`.** If your process crashes mid-flight, the same key on retry guarantees the request lands at most once.
</Tip>

<Tip>
  A key is bound to one request body. To run a different operation — a new amount or recipient — generate a new key.
</Tip>

***

## Pagination

List endpoints (`GET /parties`, `GET /accounts`, `GET /transfers`, etc.) accept four query parameters:

| Parameter   | Type    | Default     | Description                |
| ----------- | ------- | ----------- | -------------------------- |
| `page`      | integer | `1`         | 1-based page number        |
| `size`      | integer | `100`       | Items per page (minimum 1) |
| `sortOn`    | string  | `createdAt` | Field to sort by           |
| `sortOrder` | string  | `ASC`       | `ASC` or `DESC`            |

### Request

```bash theme={null}
curl "https://api.venlyfinance.com/v1/accounts?page=2&size=50&sortOrder=DESC" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response shape

Every paginated response wraps the result list with a `pagination` object:

```json theme={null}
{
  "success": true,
  "result": [
    { "id": "...", "...": "..." }
  ],
  "pagination": {
    "pageNumber": 2,
    "pageSize": 50,
    "numberOfElements": 384,
    "numberOfPages": 8,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}
```

<Tip>
  **Iterate using `hasNextPage`**, not by computing `pageNumber * pageSize >= numberOfElements`. The total count can shift between requests; the boolean is authoritative.
</Tip>

***

## Versioning

Both APIs use **URL path versioning**. The major version is in the base URL:

| API                      | Base URL                                  |
| ------------------------ | ----------------------------------------- |
| Fundflow API             | `https://api-fundflow.venly.io/v1`        |
| Finance API (production) | `https://api.venlyfinance.com/v1`         |
| Finance API (staging)    | `https://api-staging.venlyfinance.com/v1` |

### What counts as a breaking change

Breaking changes ship in a **new major version** (e.g. `/v2`). The old version stays live throughout the deprecation window.

| Breaking                           | Non-breaking (ships within the current version) |
| ---------------------------------- | ----------------------------------------------- |
| Removing a field from a response   | Adding a new field to a response                |
| Renaming a field                   | Adding a new optional request field             |
| Changing a field's type            | Adding a new endpoint                           |
| Making an optional input required  | Adding a new enum value                         |
| Removing an endpoint               | Adding a new error code                         |
| Renaming or removing an enum value | Tightening a previously undocumented validation |

<Warning>
  **Treat unknown enum values gracefully.** New enum values are *not* breaking — your client should ignore values it doesn't recognise rather than throwing. This is the most common cause of integrations failing on minor releases.
</Warning>

### Deprecation policy

* New major versions are announced **at least 6 months** before the old version is retired
* Both versions run in parallel during the deprecation window
* Migration guides are published alongside the new version
* Deprecated endpoints return a `Deprecation` HTTP header pointing to the replacement

***

## See also

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/getting-started/authentication">
    OAuth2 token exchange, refresh, and environment URLs.
  </Card>

  <Card title="Endpoints & URLs" icon="globe" href="/getting-started/endpoints">
    Full base URL reference for every environment.
  </Card>
</CardGroup>