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.

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

Scenario	Response
Same key, same body (retry)	Returns the original 2xx response — no duplicate created
Same key, different body	422 Unprocessable Entity — key already used for a different request
Missing key on a required endpoint	400 Bad Request

When to use

Required	Optional	Not applicable
Transfers (fiat / crypto / A2A)	Most other POST endpoints	GET requests (already idempotent)
Payment requests		PATCH updates (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.

Idempotency keys are bound to the exact request body. Don’t reuse a key across requests with different amounts or recipients — that returns 422, not the original response.

---

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-staging.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/api/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

---

See also

Authentication

OAuth2 token exchange, refresh, and environment URLs.

Endpoints & URLs

Full base URL reference for every environment.