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)
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

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

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

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:

{
  "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.

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

Versioning

What counts as a breaking change

Deprecation policy

See also

Authentication

Endpoints & URLs

​Idempotency

​Behaviour

​When to use

​Pagination

​Request

​Response shape

​Versioning

​What counts as a breaking change

​Deprecation policy

​See also

Authentication

Endpoints & URLs

Idempotency

Behaviour

When to use

Pagination

Request

Response shape

Versioning

What counts as a breaking change

Deprecation policy

See also