API Conventions

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.

{
  "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)
		`PATCH` on parties/accounts (use the `version` field for optimistic locking)
Virtual bank account creation		`DELETE` requests
Fiat-to-crypto payment sessions

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.

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

Pagination

Pagination is per endpoint — not every list is paginated, and one paginated list does not sort. Check the endpoint’s own reference page; the parameters below are the full set where they apply.

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	`DESC`	`ASC` or `DESC`. Applied only together with `sortOn` — on its own it is ignored

Which endpoints take them (Finance API):

Endpoints	Parameters
`GET /parties`, `GET /accounts`, `GET /accounts/{id}/transfers`, `GET /accounts/{id}/payouts`, `GET /accounts/{id}/virtual-bank-accounts`, `GET /parties/{id}/payout-bank-accounts`	all four
`GET /accounts/{id}/wallets`	`page` and `size` only — no sorting
`GET /webhooks`, `GET /supported-assets`, `GET /accounts/{id}/supported-assets`, `GET /accounts/{id}/party-roles`, `GET /accounts/{id}/payout-routes`, and the wallet `permits` / `allowances` reads	not paginated — the full list is returned

An unpaginated list returns everything in one response and carries no pagination object. Don’t write a paging loop against those — check for the object rather than assuming it is there.

Request

curl "https://api.venlyfinance.com/v1/accounts?page=2&size=50&sortOn=createdAt&sortOrder=ASC" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response shape

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

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

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

Without sortOn, lists are ordered by createdAt descending — newest first — and sortOrder is ignored. ?sortOrder=ASC on its own does not reverse a list; send sortOn=createdAt&sortOrder=ASC.

Request headers

Two optional headers apply to every Finance API endpoint.

Selecting a tenant (`x-tenant-id`)

If your token grants more than one tenant, every request must say which tenant it’s for:

curl https://api-staging.venlyfinance.com/v1/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant-id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"

With a single-tenant token — the usual case — leave it out. A value you send must exactly match a tenant the token grants. Missing when required, blank, malformed or naming a tenant the token doesn’t grant: each gets the same generic 403 forbidden, which reveals neither whether a tenant exists nor which ones you may use. Send the header once — a repeated header is rejected the same way.

Tracing a call (`X-Correlation-Id`)

Every response, including 401 and 403, carries an X-Correlation-Id header that identifies the operation in our logs. Quote it in a support request and we can find the call, along with anything we exchanged with a payment provider on its behalf. You can supply your own, as X-Correlation-Id (or X-Request-Id as a fallback), to tie our logs to yours. It must match ^[A-Za-z0-9_.:-]{1,64}$. A value outside that shape is replaced with a generated one rather than rejected, so a malformed value never fails a call.

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

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.

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

Authentication

OAuth2 token exchange, refresh, and environment URLs.

Endpoints & URLs

Full base URL reference for every environment.

Introduction

Idempotency

Behaviour

When to use

Request

Response shape

Request headers

Selecting a tenant (`x-tenant-id`)

Tracing a call (`X-Correlation-Id`)

Versioning

What counts as a breaking change

Deprecation policy

See also

Authentication

Endpoints & URLs

​Idempotency

​Behaviour

​When to use

​Pagination

​Request

​Response shape

​Request headers

​Selecting a tenant (x-tenant-id)

​Tracing a call (X-Correlation-Id)

​Versioning

​What counts as a breaking change

​Deprecation policy

​See also

Authentication

Endpoints & URLs

Idempotency

Behaviour

When to use

Pagination

Request

Response shape

Request headers

Selecting a tenant (`x-tenant-id`)

Tracing a call (`X-Correlation-Id`)

Versioning

What counts as a breaking change

Deprecation policy

See also