Upgrade to v3 - Data API

This guide covers breaking changes when upgrading from major version v2 to v3. Fiskil v3 reworks the two Core Resources list endpoints — consents and end users — to return a paginated response object instead of a bare array, and renames consent fields to camelCase.

Coming from v1? See Coming from v1? below — you apply the v1 -> v2 changes plus everything on this page.

Before upgrading your pinned version

Upgrade your pinned version in Console only after thorough testing with X-Fiskil-Version. Console upgrades are one-way (for example, v2 -> v3) and cannot be downgraded in settings.

What hasn't changed

No URL changes — every endpoint path and HTTP method is identical - No Banking or Energy changes — all /banking/* and /energy/* endpoints are identical to v2 - No auth changes — authentication and security are unchanged - Only two GET responses are affected — GET /consent and GET /end-users; see below for exact schema changes

1. Opt into v3 with a header

v1, v2, and v3 are served on the same base URL. Select v3 per request with the X-Fiskil-Version header:

curl https://api.fiskil.com/v1/consent \
  -H 'X-Fiskil-Version: v3' \
  -H 'Authorization: Bearer {token}'

In v3, the X-Fiskil-Version header is documented as required on the two changed endpoints — always send it explicitly while migrating rather than relying on your Console pin.

For the full header and Console-pin semantics, see API Versioning.

2. Migration checklist

Pin production requests to your current version

Deploy a one-line change adding X-Fiskil-Version: v2 (or v1) header to your requests. This freezes your current response shape while you prepare the upgrade.

Check whether affected endpoints are used

If your integration uses either of these endpoints, review the exact schema changes in the sections below:

GET /consent
GET /end-users

If you use neither, v3 needs no parser changes.

Update affected parsers

Work through the breaking changes below: read the new response envelopes, rename consent fields to camelCase, and stop sending expires_before.

Test v3 with production traffic

Run X-Fiskil-Version: v3 in production for a period of time and verify both endpoints and downstream parsing before changing the Console pin.

Upgrade the Console pinned version

After production validation, upgrade your account's pinned API version in Console to v3.

3. Breaking changes

What this section covers

Only breaking changes are documented below (for example type changes, structural replacements, or removed fields). Additive updates such as the new pagination parameters are covered in New in v3. For full request and response shapes, see each endpoint's API reference and OpenAPI specification.

In v3, the response body is no longer a bare JSON array of consents. It is an object with a consents array and an optional links object for pagination.

v1 / v2	v3	Notes
top-level array `[...]`	object `{ "consents": [...], "links": {...} }`	Structure changed
—	`links.next` / `links.prev` string URLs	New, optional

Example v3 response:

{
  "consents": [
    {
      "arrangement_id": "94549a73-a554-4b76-b824-d96898829751",
      "active": true
      ...
    }
  ],
  "links": {
    "next": "/consent?page[after]=eyJpZCI6...",
    "prev": "/consent?page[before]=eyJpZCI6..."
  }
}

Migrate: Read the consent list from consents array instead of iterating the top-level array. Treat links as optional — it carries cursor URLs when more pages exist.

GET /end-users - response envelope changed

In v3, the response body is an object with an end_users array and an optional links object, instead of a bare array. Note the wrapper key is snake_case (end_users), unlike consents. The end-user item fields (id, email, name, phone) are unchanged.

v1 / v2	v3	Notes
top-level array `[...]`	object `{ "end_users": [...], "links": {...} }`	Structure changed
item fields	unchanged (`id`, `email`, `name`, `phone`)	No renames

Example v3 response:

{
  "end_users": [
    {
      "email": "john_starmer@gmail.com",
      "id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
      "name": "John Starmer",
      "phone": "+614123456789"
    }
  ],
  "links": {
    "next": "/end-users?page[after]=eyJpZCI6..."
  }
}

Migrate: Read the list from end_users array instead of the top-level array. Item parsing is unchanged.

In v3, the two list endpoints return a simpler JSON error body. The temporary, timeout, and fault fields are removed.

v1 / v2	v3
`{ id, message, name, temporary, timeout, fault }`	`{ id, message, name }`

Example v2 error response:

{
  "name": "invalid_field_type",
  "id": "Iinv0AfL",
  "message": "invalid value ...",
  "temporary": false,
  "timeout": false,
  "fault": false
}

Example v3 error response:

{
  "id": "3GFbIj0u9muOrByxbdINUACrYRa",
  "name": "bad request",
  "message": "invalid active value ..."
}

Migrate: Handle 400 and 500 on both list endpoints and parse the error body as { id, message, name }. Stop relying on the fault, temporary, and timeout fields for these endpoints.

4. New in v3 (non-breaking)

Both GET /consent and GET /end-users gain cursor-based pagination:

Parameter	Type	Description
`page[size]`	integer	Number of items per page, capped at 1000
`page[after]`	string	Cursor — return results after this position
`page[before]`	string	Cursor — return results before this position

curl 'https://api.fiskil.com/v1/end-users?page[size]=100' \
  -H 'X-Fiskil-Version: v3' \
  -H 'Authorization: Bearer {token}'

Follow links.next / links.prev from the response to walk pages. Requests without page[...] parameters keep working — pagination is opt-in. See the Pagination guide for more details.

5. Coming from v1?

v3 uses the same Banking and Energy service versions as v2, so upgrading from v1 directly to v3 means applying both sets of breaking changes:

All v1 -> v2 changes — banking products/accounts rates and fees, transactions extended_data, and the removed identity customer field. Work through the Upgrade to v2 guide.
All v2 -> v3 changes — the consents and end-users changes on this page.

You can validate both sets in one pass: test with X-Fiskil-Version: v3 and follow the migration checklist above, treating the endpoints from both guides as your affected list. There is no need to pin to v2 along the way.

6. Reference

Version switcher in docs: Toggle between v1, v2, and v3 in the top navigation to compare API reference shapes. This only affects docs — runtime behavior is controlled by the X-Fiskil-Version header or your Console pin.

How versioning works at Fiskil: For the versioning model, breaking-change policy, and support timeline, see API Versioning.

Need help? Use the AI chat in the bottom-right corner — it has context on all specs. For anything it can't resolve, reach out to Fiskil support.