Requests and responses
API Documentation / API Conventions
Base URL and version
All resource examples use the proposed production base URL:
https://api.finov.io/v1
OAuth endpoints are not versioned under /v1. Sandbox and regional base URLs will be documented before public release.
Headers
Send these headers with JSON API requests:
Authorization: Bearer {access_token}
Accept: application/json
Content-Type: application/json
Content-Type is required only when a request has a JSON body. UTF-8 is the default character encoding.
Identifiers and dates
- Resource identifiers are UUID strings and must be treated as opaque.
- Calendar dates use
YYYY-MM-DD. - Timestamps use RFC 3339 in UTC, for example
2026-08-10T09:30:00Z. - Decimal monetary values are JSON strings, for example
"1250.00", to avoid binary floating-point loss. - Currency codes use ISO 4217 uppercase codes such as
NZDandAUD. - Country codes use ISO 3166-1 alpha-3 codes such as
NZLandAUS.
Resource representation
A single-resource response returns the resource directly:
{
"id": "3bcf2f35-e49b-4b35-a1cb-56f4ccf1c71a",
"name": "Northwind Supplies",
"created_at": "2026-08-10T09:30:00Z",
"updated_at": "2026-08-10T09:30:00Z"
}
Collection responses use a data array and meta object. See Pagination.
Create operations return 201 Created with the created resource and a Location header. Successful updates return 200 OK with the updated resource. Successful deletes return 204 No Content.
Unknown fields and null values
Clients must ignore unknown response fields so compatible additions do not break integrations. Finovio rejects unknown request fields with a validation error to catch misspelled or unsupported input.
Optional fields that have no value are returned as null when the field is part of that representation. Fields omitted because of scope or endpoint shape are not equivalent to null.
Idempotency
The initial contract does not promise idempotency-key support. Do not automatically retry POST requests after an ambiguous network failure. Retrieve or reconcile the resource before deciding whether to submit again.
Safe HTTP methods such as GET may be retried with bounded exponential backoff. Retry rate-limit and service errors only as described in Rate limits and versioning.