Skip to main content

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.

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

ScenarioResponse
Same key, same body (retry)Returns the original 2xx response — no duplicate created
Same key, different body422 Unprocessable Entity — key already used for a different request
Missing key on a required endpoint400 Bad Request

​
When to use

RequiredOptionalNot applicable
Transfers (fiat / crypto / A2A)Most other POST endpointsGET requests (already idempotent)
Payment requestsPATCH updates (use the version field for optimistic locking)
Virtual bank account creationDELETE 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:
ParameterTypeDefaultDescription
pageinteger11-based page number
sizeinteger100Items per page (minimum 1)
sortOnstringcreatedAtField to sort by
sortOrderstringASCASC 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:
APIBase URL
Fundflow APIhttps://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.
BreakingNon-breaking (ships within the current version)
Removing a field from a responseAdding a new field to a response
Renaming a fieldAdding a new optional request field
Changing a field’s typeAdding a new endpoint
Making an optional input requiredAdding a new enum value
Removing an endpointAdding a new error code
Renaming or removing an enum valueTightening 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.