# Fiskil Documentation
# Generated for LLM consumption
# Total pages: 259
# ---

# CMS Editing Guide (/cms-guide)

Guide for content editors using the Sveltia CMS



CMS Editing Guide [#cms-editing-guide]

This guide helps content editors use the CMS to manage documentation content for Fiskil's products.

Accessing the CMS [#accessing-the-cms]

1. Navigate to your CMS admin URL (e.g., `https://your-domain.com/admin`)
2. Click "Login with GitHub"
3. Authorize the application
4. You'll be redirected to the CMS interface

Creating New Documentation [#creating-new-documentation]

Step 1: Select a Collection [#step-1-select-a-collection]

Choose the appropriate collection for your content:

* **Data API - Guides**: General guides for the Data API product
* **Data API - Changelog**: Version updates and changes
* **Data Holder - Guides**: General guides for the Data Holder product
* **Data Holder - API Reference**: API endpoint documentation
* **Data Holder - Changelog**: Version updates and changes

Step 2: Create New Entry [#step-2-create-new-entry]

1. Click "New \[Collection Name]"
2. Fill in the required fields:
   * **Title**: Page title (shown in navigation)
   * **Description**: Brief summary (used for SEO and previews)
   * **Body**: Main content in Markdown/MDX format

Step 3: Add Translations [#step-3-add-translations]

1. Save the English version first
2. Click the locale dropdown and select "Spanish (es)"
3. Translate the title, description, and body content
4. Save the Spanish version

Available MDX Components [#available-mdx-components]

When editing the body content, you can use these custom components:

Cards [#cards]

Display linked cards for navigation:

```jsx
<Cards>
  <Card title="Getting Started" href="/data-holder/guides/get-started/quickstart" />
  <Card title="Configuration" href="/data-holder/guides/configure/custom-domains" />
</Cards>
```

Callouts [#callouts]

Highlight important information:

```jsx
<Callout type="info">
Important information here
</Callout>
```

Available types:

* `info` - General information (blue)
* `warn` - Warnings (yellow)
* `tip` - Helpful tips (green)
* `idea` - Ideas or suggestions (purple)

Alias components (same as Callout with different default types):

```jsx
<Note>Note content</Note>
<Info>Info content</Info>
<Tip>Tip content</Tip>
<Warning>Warning content</Warning>
<Check>Success message</Check>
```

Steps [#steps]

Create step-by-step guides:

```jsx
<Steps>
<Step>
## First step

Content for the first step goes here.
</Step>
<Step>
## Second step

Content for the second step goes here.
</Step>
</Steps>
```

Tabs [#tabs]

Show code examples in multiple languages:

```jsx
<Tabs items={["Node.js", "Python", "cURL"]}>
  <Tab value="Node.js">
  Code content here
  </Tab>
  <Tab value="Python">
  Code content here
  </Tab>
  <Tab value="cURL">
  Code content here
  </Tab>
</Tabs>
```

See existing documentation pages for complete examples of the Tabs component with code blocks.

Accordion [#accordion]

Create collapsible content sections:

```jsx
<AccordionGroup>
  <Accordion title="What is this feature?">
  Detailed explanation of the feature goes here.
  </Accordion>
  <Accordion title="How do I use it?">
  Step-by-step instructions go here.
  </Accordion>
</AccordionGroup>
```

Mermaid Diagrams [#mermaid-diagrams]

Create flowcharts and diagrams:

```jsx
<Mermaid chart={`
graph TD
  A[Start] --> B[Process Data]
  B --> C{Is Valid?}
  C -->|Yes| D[Success]
  C -->|No| E[Error]
`} />
```

API Response Fields [#api-response-fields]

Document API response fields:

```jsx
<ResponseField name="id" type="string" required>
Unique identifier for the resource
</ResponseField>

<ResponseField name="created_at" type="timestamp">
ISO 8601 timestamp of when the resource was created
</ResponseField>
```

Code Blocks [#code-blocks]

Regular markdown code blocks with syntax highlighting:

````markdown
```javascript
function example() {
  return "Hello, world!"
}
```
````

Supported languages: javascript, typescript, python, bash, json, yaml, and more.

Working with Images [#working-with-images]

Uploading Images [#uploading-images]

1. While editing a document, click the image button in the toolbar
2. Click "Upload" or drag and drop an image
3. The image will be stored in `/public/images/`
4. The CMS will insert the markdown: `![Alt text](/images/filename.png)`

Image Best Practices [#image-best-practices]

* Compress images before uploading (use TinyPNG or similar tools)
* Use descriptive alt text for accessibility
* Recommended formats: PNG for screenshots, JPG for photos, SVG for icons
* Keep file sizes under 500KB when possible

Managing Navigation [#managing-navigation]

To change the order of pages in the sidebar:

1. Go to "Navigation" collection
2. Select the appropriate meta file:
   * **Root Navigation**: Top-level sections
   * **Data API Navigation**: Data API section pages
   * **Data Holder Navigation**: Data Holder section pages
3. Edit the "Pages" list to reorder or add/remove pages
4. Save changes

Multi-Locale Workflow [#multi-locale-workflow]

English to Spanish Translation [#english-to-spanish-translation]

1. Create and save the English version first
2. Switch locale dropdown from "en" to "es"
3. Translate each field (title, description, body)
4. Keep the same component structure (translate text only)
5. Save the Spanish version

Translation Tips [#translation-tips]

* Maintain the same MDX component structure
* Translate component content but keep prop names in English
* Keep URLs and code examples unchanged
* Use consistent terminology across translations

Saving and Publishing [#saving-and-publishing]

Committing Changes [#committing-changes]

When you save:

1. Click "Save" button
2. Enter a descriptive commit message
3. Changes are committed directly to the Git repository
4. The site will automatically rebuild and deploy

Commit Message Guidelines [#commit-message-guidelines]

Good commit messages:

* "Update quickstart guide with new authentication steps"
* "Add Spanish translation for API reference"
* "Fix broken link in changelog"

Poor commit messages:

* "update"
* "changes"
* "fix"

Preview Mode [#preview-mode]

Before saving:

1. Click "Preview" to see how your content will look
2. Check that all components render correctly
3. Verify links work as expected
4. Review both English and Spanish versions

Troubleshooting [#troubleshooting]

Content Not Appearing [#content-not-appearing]

* Verify you saved the changes
* Check the Git commit was created successfully
* Wait 2-3 minutes for the site to rebuild
* Clear your browser cache

Components Not Rendering [#components-not-rendering]

* Check MDX syntax matches the examples above
* Ensure opening and closing tags match
* Verify component names are capitalized correctly
* Check for missing props (e.g., `items` in Tabs)

Images Not Loading [#images-not-loading]

* Verify image path starts with `/images/`
* Check image file exists in `/public/images/`
* Ensure image filename has no spaces (use hyphens instead)

Translation Missing [#translation-missing]

* Switch to the correct locale (en/es) using dropdown
* Save each locale version separately
* Verify the file exists in the correct folder structure

Getting Help [#getting-help]

* **Technical Issues**: Contact the development team
* **Content Questions**: Refer to existing documentation as examples
* **Component Usage**: Check component examples in existing pages
* **Translation Help**: Use existing Spanish pages as reference

Best Practices [#best-practices]

1. **Test Before Publishing**: Always preview changes before saving
2. **Descriptive Commits**: Write clear commit messages
3. **Consistent Style**: Follow existing documentation patterns
4. **Link Checking**: Test all links after adding them
5. **Image Optimization**: Compress images before uploading
6. **Translation Consistency**: Use consistent terminology across locales
7. **Component Guidelines**: Use components appropriately (don't overuse Callouts)
8. **Regular Saves**: Save work frequently to avoid losing changes


---

# Changelog (/data-api/changelog)

Release notes and versioning updates for the Fiskil Data API.



All changes to the Data API are listed here. For changes made before the new
versioning model, see the [Legacy Changelog](/data-api/changelog/legacy).

For how version selection works — the `X-Fiskil-Version` header, Console pinning, and what
counts as a breaking change — see [API Versioning](/data-api/guides/core-concepts/versioning).

<ChangelogLayout>
  v3.2.0 [#v320]

  19-08-2026 (v3.2.0) [#19-08-2026-v320]

  * New feature: Added `GET /v1/data-freshness` endpoint to retrieve freshness information and last refresh timestamps for datasets.
  * Update: Removed the `meta` object from the transactions response introduced in the previous minor version.

  v3.1.0 [#v310]

  31-07-2026 (v3.1.0) [#31-07-2026-v310]

  * New feature: Get transactions endpoint now includes `meta` object with last updated time per account

  v3.0.0 [#v300]

  08-07-2026 (v3.0.0) [#08-07-2026-v300]

  Initial release of major version `v3`. `v3` is now the current major version
  for new accounts.

  This release introduces breaking changes for two Core Resources endpoints:

  * Consents: `GET /consent` (list consents)
  * End Users: `GET /end-users` (list end users)

  Banking and Energy endpoints are unchanged from `v2`.

  New in `v3`: cursor-based pagination (`page[before]`, `page[after]`,
  `page[size]`) and a `links` object on the consents and end-users list
  responses.

  See the [v2 -> v3 upgrade guide](/data-api/changelog/upgrade-guide-v3) for the
  exact request and response schema changes.

  ***

  v2.2.0 [#v220]

  19-08-2026 (v2.2.0) [#19-08-2026-v220]

  * New feature: Added `GET /v1/data-freshness` endpoint to retrieve freshness information and last refresh timestamps for datasets.
  * Update: Removed the `meta` object from the transactions response introduced in the previous minor version.

  v2.1.0 [#v210]

  31-07-2026 (v2.1.0) [#31-07-2026-v210]

  * New feature: Get transactions endpoint now includes `meta` object with last updated time per account

  v2.0.1 [#v201]

  25-06-2026 (v2.0.1) [#25-06-2026-v201]

  * Bug fix: Added missing `arrangement_id` field to the energy invoices endpoint.
  * Bug fix: Add 429 status code for banking balance endpoint with live `fetch=true`.
  * New feature: Get consents endpoints now support the `expires_before` query parameter.

  v2.0.0 [#v200]

  07-04-2026 (v2.0.0) [#07-04-2026-v200]

  Initial release of major version `v2`.

  This release introduces breaking changes for:

  * Identity: `GET /common/identity`
  * Banking: `GET /banking/transactions`
  * Banking: `GET /banking/products/{product_id}`
  * Banking: `GET /banking/accounts`

  See the [v1 -> v2 upgrade guide](/data-api/changelog/upgrade-guide) for the exact
  response schema changes.

  ***

  v1.2.0 [#v120]

  19-08-2026 (v1.2.0) [#19-08-2026-v120]

  * New feature: Added `GET /v1/data-freshness` endpoint to retrieve freshness information and last refresh timestamps for datasets.
  * Update: Removed the `meta` object from the transactions response introduced in the previous minor version.

  v1.1.0 [#v110]

  31-07-2026 (v1.1.0) [#31-07-2026-v110]

  * New feature: Get transactions endpoint now includes `meta` object with last updated time per account

  v1.0.1 [#v101]

  25-06-2026 (v1.0.1) [#25-06-2026-v101]

  * Bug fix: Added missing `arrangement_id` field to the energy invoices endpoint.
  * Bug fix: Add 429 status code for banking balance endpoint with live `fetch=true`.
  * New feature: Get consents endpoints now support the `expires_before` query parameter.

  v1.0.0 [#v100]

  07-04-2026 (v1.0.0) [#07-04-2026-v100]

  Baseline major version at the start of the new versioning model.

  No breaking changes were introduced in `v1.0.0`. It keeps the same response
  shapes as the pre-versioning API endpoints below and all existing customers were
  pinned to it by default.

  * Core Resources: Institutions, Consents, End Users
  * Banking APIs: Accounts, Transactions, Balances
  * Energy APIs: Service Points, Usage
  * Webhook integrations for data sync events
</ChangelogLayout>


---

# Legacy Changelog (/data-api/changelog/legacy)

Pre-reset changelog entries for the Fiskil Data API (prior to the 2026-04-07 v2.0.0 version reset).



<Callout type="info" title="Pre-reset historical changelog">
  These entries are from before 7 April 2026, when we reset the Data API to v2.0.0 and adopted a new versioning policy. They use the previous v2.0.x numbering and are kept here for historical reference only. For current releases, see the [Changelog](/data-api/changelog).
</Callout>

<ChangelogLayout>
  v2 (Pre-reset) [#v2-pre-reset]

  26-02-2026 (v2.0.11) [#26-02-2026-v2011]

  Updated Data Services APIs to v1.8.2

  Energy: Plans endpoint [#energy-plans-endpoint]

  * Added a new `status` query parameter to filter returned plans by `active` or `all` (defaults to `active`).

  ***

  16-01-2026 (v2.0.10) [#16-01-2026-v2010]

  Updated Core APIs to v1.1.9

  Core: Institutions endpoint [#core-institutions-endpoint]

  * Added new `status` field to the response.

  The institutions endpoint now returns a `status` field which indicates the current connection or consent flow status of the institution.

  ***

  14-01-2026 (v2.0.9) [#14-01-2026-v209]

  Updated Data Services APIs to v1.8.1

  Banking: Balance endpoint [#banking-balance-endpoint]

  * Introduced optional `X-Fiskil-*` request headers to improve real-time balance retrieval.

  When provided, these headers allow the request to be treated as a consumer-present API call, improving traffic classification and handling.

  ***

  18-12-2025 (v2.0.8) [#18-12-2025-v208]

  Updated Data Services APIs to v1.8.0

  Energy: ServicePoints [#energy-servicepoints]

  * Added new Date field: `ServicePoint.lastConsumerChangeDate` - The date the account holder changed for the NMI

  Banking: Transactions [#banking-transactions]

  * Added new `extended_data` extension type: `nppPayload` - Payload specific to NPP overlay service
  * Deprecated `extended_data.service` field - Identifier of the applicable overlay service
  * Deprecated `extended_data.x2p101_payload` object - Payload specific to x2p101 overlay service

  The deprecated fields in the Banking Transactions API will be removed in future releases. Please update your applications to use the new `nppPayload` extension instead of the deprecated `x2p101` extension.

  ***

  13-05-2025 (v2.0.7) [#13-05-2025-v207]

  * Introduced delivery attempt field for webhook sync events to keep track of retries and handle deduplication.

  ***

  15-03-2025 (v2.0.6) [#15-03-2025-v206]

  * Introduced `banking.transactions.basic.sync.completed` event for basic transaction data sync

  ***

  12-09-2024 (v2.0.5) [#12-09-2024-v205]

  * Adds better example data and field descriptions to Banking APIs

  ***

  03-05-2024 (v2.0.4) [#03-05-2024-v204]

  * APIs - Display a list of "enum" values, when applicable.

  ***

  16-04-2024 (v2.0.4) [#16-04-2024-v204]

  * Errors page - Added details for various "error types".

  ***

  01-02-2024 (v2.0.4) [#01-02-2024-v204]

  * Corrected typo in introduction
  * Added missing /v1 to API endpoint
  * Corrected institution model description
  * Added endpoint for Info permission
  * Email address is required to create end user
  * Corrected description of Revoke Consent API
  * Corrected description for `page[before]` query parameters
  * Removed JWT parameter from identity API (All API endpoints should assume that an access token is required to invoke them)
  * Added example for common/identity response

  ***

  29-01-2024 (v2.0.3) [#29-01-2024-v203]

  * Energy APIs - Fixed a typo in the invoices endpoint path. Replaced "invoices" (plural) with "invoice" (single).

  ***

  14-12-2023 (v2.0.2) [#14-12-2023-v202]

  * Energy APIs - Typo fix for all the properties containing "utype" at the end. Replaced "utype" with "u\_type". Here's the list of affected properties - `address_u_type`, `rate_block_u_type`, `method_u_type`, `tariff_u_type`, `transaction_u_type`, `payment_schedule_u_type`, `read_u_type`.

  ***

  01-12-2023 (v2.0.1) [#01-12-2023-v201]

  * Core Resources - Added "Retrieve an institution by id" API

  ***

  25-09-2023 (v2.0.0) [#25-09-2023-v200]

  Initial release of version 2.0.0.

  * Full support for Energy APIs (Plans, Service Points, Invoices, Usage)
  * Full support for Banking APIs (Accounts, Transactions, Balances, Direct Debits, Scheduled Payments)
  * Core APIs for Institutions, Consents, and End Users
  * Webhook event integrations for data sync notifications
</ChangelogLayout>


---

# Upgrade to v3 (/data-api/changelog/upgrade-guide-v3)

Migration guide for upgrading the Fiskil Data API from v2 or v1 to v3



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?](#5-coming-from-v1) below — you apply
the `v1` -> `v2` changes plus everything on this page.

<Callout type="warning" title="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.
</Callout>

<Callout type="success" title="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
</Callout>

1. Opt into v3 with a header [#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:

```bash
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](/data-api/guides/core-concepts/versioning#selecting-a-version).

2. Migration checklist [#2-migration-checklist]

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Update affected parsers">
    Work through the breaking changes below: read the new response envelopes,
    rename consent fields to camelCase, and stop sending `expires_before`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Upgrade the Console pinned version">
    After production validation, upgrade your account's pinned API version in
    Console to `v3`.
  </Step>
</Steps>

3. Breaking changes [#3-breaking-changes]

<Callout type="info" title="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](#4-new-in-v3-non-breaking). For full request and response shapes, see each
  endpoint's API reference and OpenAPI specification.
</Callout>

GET /consent - response envelope changed [#get-consent---response-envelope-changed]

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:**

```json
{
  "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 [#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:**

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

GET /consent & GET /end-users - error responses changed [#get-consent--get-end-users---error-responses-changed]

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:**

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

**Example v3 error response:**

```json
{
  "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) [#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 |

```bash
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](/data-api/api-reference/pagination) guide for more details.

5. Coming from v1? [#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:

1. **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](/data-api/changelog/upgrade-guide) guide.
2. **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](#2-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 [#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](/data-api/guides/core-concepts/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.


---

# Upgrade to v2 (/data-api/changelog/upgrade-guide)

Migration guide for upgrading the Fiskil Data API from v1 to v2



This guide covers breaking changes when upgrading from major version `v1` to
`v2`. Fiskil aligns the v2 banking product and transaction models more closely
with the shapes returned by banks, updates the banking accounts response shape,
and removes a deprecated field from identity.

<Callout type="warning" title="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, `v1` -> `v2`)
  and cannot be downgraded in settings.
</Callout>

<Callout type="success" title="What hasn't changed">
  * **No URL changes** — every endpoint path and HTTP method is identical
  * **No request changes** — query params, path params, and request bodies are unchanged
  * **No auth changes** — authentication, consents, and security are unchanged
  * **Only four GET responses are affected** — see below for exact schema changes
</Callout>

1. Opt into v2 with a header [#1-opt-into-v2-with-a-header]

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

```bash
curl https://api.fiskil.com/v1/banking/products/{product_id} \
  -H 'X-Fiskil-Version: v2' \
  -H 'Authorization: Bearer {token}'
```

For the full header and Console-pin semantics, see [API Versioning](/data-api/guides/core-concepts/versioning#selecting-a-version).

2. Migration checklist [#2-migration-checklist]

<Steps>
  <Step title="Pin production requests to v1">
    Deploy a one-line change adding `X-Fiskil-Version: v1` header to your requests.
    This freezes your current response shape while you prepare the upgrade.
  </Step>

  <Step title="Check whether affected endpoints are used">
    If your integration uses any of these endpoints, review the exact schema
    changes in the sections below:

    * `GET /common/identity`
    * `GET /banking/transactions`
    * `GET /banking/products/{id}`
    * `GET /banking/accounts`
  </Step>

  <Step title="Update affected parsers">
    Work through the breaking changes below and update the fields your code
    consumes.
  </Step>

  <Step title="Test v2 with production traffic">
    Run `X-Fiskil-Version: v2` in production for a period of time and verify all
    affected endpoints and downstream parsing before changing the Console pin.
  </Step>

  <Step title="Upgrade the Console pinned version">
    After production validation, upgrade your account's pinned API version in
    Console to `v2`.
  </Step>
</Steps>

3. Breaking changes [#3-breaking-changes]

<Callout type="info" title="What this section covers">
  Only **breaking** changes are documented below (for example type changes,
  structural replacements, or removed fields). **Additive** updates and other
  non-breaking differences are not listed here. For full request and response
  shapes, including new optional fields, see each endpoint's API reference and
  OpenAPI specification.
</Callout>

GET /banking/products/id - deposit & lending rates changes [#get-bankingproductsid---deposit--lending-rates-changes]

In `v2`, each **deposit rate** and **lending rate** stores tier bounds
(`minimum_value`, `maximum_value`) as **strings**, not numbers.
**Applicability** for a rate (or tier) is now an **array** of
`applicability_conditions` objects, not a single nested object.

| v1                                        | v2                             | Notes              |
| ----------------------------------------- | ------------------------------ | ------------------ |
| `tiers[].minimum_value` number            | `tiers[].minimum_value` string | Field type changed |
| `tiers[].maximum_value` number            | `tiers[].maximum_value` string | Field type changed |
| `applicability_conditions` object         | array of objects               | structure changed  |
| `tiers[].applicability_conditions` object | array of objects               | structure changed  |

**Example v2 response:**

```json
{
  "deposit_rates": [
    {
      "additional_info": "Applicable to currency NZD",
      "additional_info_uri": "https://www.commbank.com.au/business/international/international-payments/foreign-currency-accounts.html#rates",
      "application_frequency": "P1M",
      "application_type": "PERIODIC",
      "calculation_frequency": "P1D",
      "deposit_rate_type": "VARIABLE",
      "rate": "0",
      "tiers": [
        {
          "maximum_value": "59999.99",
          "minimum_value": "0.00",
          "name": "Amount",
          "rate_application_method": "WHOLE_BALANCE",
          "unit_of_measure": "DOLLAR"
        }
      ],
      "applicability_conditions": [
        {
          "rate_applicability_type": "NEW_CUSTOMER",
          "additional_value": "NZD",
          "additional_info": "Applicable to currency NZD",
          "additional_info_uri": "https://www.commbank.com.au/business/international/international-payments/foreign-currency-accounts.html#rates"
        }
      ]
    }
  ], 
  "lending_rates": [
    {
        "additional_info": "Investment - Principal and Interest repayment type with Package",
        "additional_info_uri": "https://www.commbank.com.au/content/dam/commbank/personal/apply-online/download-printed-forms/home-loan-update-002842.pdf",
        "additional_value": "P1Y",
        "application_frequency": "P1M",
        "application_type": "PERIODIC",
        "calculation_frequency": "P1D",
        "comparison_rate": "0.0857",
        "interest_payment_due": "IN_ARREARS",
        "lending_rate_type": "FIXED",
        "loan_purpose": "INVESTMENT",
        "rate": "0.0654",
        "repayment_type": "PRINCIPAL_AND_INTEREST",
        "tiers": [
            {
                "maximum_value": "99999999.00",
                "minimum_value": "10000",
                "name": "BALANCE",
                "rate_application_method": "WHOLE_BALANCE",
                "unit_of_measure": "DOLLAR"
            }
        ]
    }
  ]
}
```

**Migrate:** On every item in `deposit_rates[]` and `lending_rates[]`, treat
`tiers[].minimum_value` and `tiers[].maximum_value` as **strings**, and parse
`applicability_conditions` as an **array** of objects with the new shape.

GET /banking/products/id - fees changes [#get-bankingproductsid---fees-changes]

In `v2`, each fee and discount has a **type** field (`fee_method_u_type` or
`discount_method_u_type`) that tells you how it is calculated. The amount or
rate lives **inside** a nested object (for example `fixed_amount` or
`rate_based`), not as a single top-level `amount` on the fee anymore.

| v1                             | v2                                                    | Notes                      |
| ------------------------------ | ----------------------------------------------------- | -------------------------- |
| flat fee fields (`amount` etc) | `fee_method_u_type` with nested objects               | Fee structure changed      |
| flat discount fields           | `discount_method_u_type` with nested discount objects | Discount structure changed |

**Example v2 response:**

```json
{
  "fees": [
    {
      "additional_info": "Any other cash withdrawals overseas will incur a $5.00 fee plus 3.5% of the transaction value. We will waive your fee if you meet certain criteria. Refer to the product terms and conditions.",
      "additional_info_uri": "https://www.commbank.com.au/personal/apply-online/download-printed-forms/SavingsInvestment_ADB2852.pdf",
      "currency": "AUD",
      "fee_method_u_type": "rateBased",
      "fee_type": "WITHDRAWAL",
      "name": "Access fee - Overseas cash withdrawals",
      "rate_based": {
        "rate": "0.035",
        "rate_type": "TRANSACTION"
      }
    },
    {
      "additional_info": "Any other cash withdrawals overseas will incur a $5.00 fee plus 3.5% of the transaction value. We will waive your fee if you meet certain criteria. Refer to the product terms and conditions.",
      "additional_info_uri": "https://www.commbank.com.au/personal/apply-online/download-printed-forms/SavingsInvestment_ADB2852.pdf",
      "currency": "AUD",
      "fee_method_u_type": "fixedAmount",
      "fee_type": "WITHDRAWAL",
      "fixed_amount": {
        "amount": "5.00"
      },
      "name": "Access fee - Overseas cash withdrawals"
    }
  ]
}
```

**Migrate:** Branch on `fee_method_u_type` and read from `fixed_amount` or
`rate_based` (and the same idea for `discount_method_u_type` on discounts).
Review any `fee_type` switch logic or enum validation so new or removed values do
not fail deserialization or routing.

GET /banking/accounts - deposit & lending rates changes [#get-bankingaccounts---deposit--lending-rates-changes]

In `v2`, **deposit\_rates** and **lending\_rates** on account payloads follow the
same rules as on **product** detail: tier bounds are **strings**, and
**applicability** is an **array** of `applicability_conditions` objects (on the
rate and on tiers), not one nested object.

| v1                                          | v2                               | Notes                  |
| ------------------------------------------- | -------------------------------- | ---------------------- |
| `*.tiers[].minimum_value` number            | `*.tiers[].minimum_value` string | Same as product detail |
| `*.tiers[].maximum_value` number            | `*.tiers[].maximum_value` string | Same                   |
| `*.applicability_conditions` object         | array of objects                 | Same                   |
| `*.tiers[].applicability_conditions` object | array of objects                 | Same                   |

**Example v2 response (fragment):**

```json
{
  "deposit_rates": [
    {
      "application_frequency": "P1M",
      "application_type": "PERIODIC",
      "calculation_frequency": "P1D",
      "deposit_rate_type": "VARIABLE",
      "rate": "0",
      "tiers": [
        {
          "maximum_value": "59999.99",
          "minimum_value": "0.00",
          "name": "Amount",
          "rate_application_method": "WHOLE_BALANCE",
          "unit_of_measure": "DOLLAR"
        }
      ],
      "applicability_conditions": [
        {
          "rate_applicability_type": "NEW_CUSTOMER",
          "additional_value": "NZD",
          "additional_info": "Applicable to currency NZD",
          "additional_info_uri": "https://www.commbank.com.au/business/international/international-payments/foreign-currency-accounts.html#rates"
        }
      ]
    }
  ],
  "lending_rates": [
    {
      "application_frequency": "P1M",
      "application_type": "PERIODIC",
      "calculation_frequency": "P1D",
      "lending_rate_type": "FIXED",
      "loan_purpose": "INVESTMENT",
      "rate": "0.0654",
      "repayment_type": "PRINCIPAL_AND_INTEREST",
      "tiers": [
        {
          "maximum_value": "99999999.00",
          "minimum_value": "10000.00",
          "name": "BALANCE",
          "rate_application_method": "WHOLE_BALANCE",
          "unit_of_measure": "DOLLAR"
        }
      ],
      "applicability_conditions": [
        {
          "rate_applicability_type": "NEW_CUSTOMER",
          "additional_value": "INVESTMENT",
          "additional_info": "Investment - Principal and Interest repayment type with Package",
          "additional_info_uri": "https://www.commbank.com.au/content/dam/commbank/personal/apply-online/download-printed-forms/home-loan-update-002842.pdf"
        }
      ]
    }
  ]
}
```

**Migrate:** Apply the same parsing updates as for product detail: string tier
bounds and array-shaped `applicability_conditions` on each rate and tier.

GET /banking/accounts - fees & discounts changes [#get-bankingaccounts---fees--discounts-changes]

In `v2`, each **fee** on an account uses `fee_method_u_type` and nests the
amount or rate under `fixed_amount` or `rate_based`. **Discounts** on a fee use
the same idea with `discount_method_u_type` instead of flat discount fields.

| Area       | v1                                                                                             | v2                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Fee        | top-level `amount`, `balance_rate`, `transaction_rate`, `accrued_rate`, `accrual_frequency`, … | `fee_method_u_type` + `fixed_amount` / `rate_based` (and related nested fields) |
| Discount   | top-level `amount`, `balance_rate`, `transaction_rate`, `accrued_rate`, `fee_rate`, …          | `discount_method_u_type` + `fixed_amount` / `rate_based`                        |
| `fee_type` | fixed enum in strict clients                                                                   | enum set can change; validate loosely or handle new values                      |

**Example v2 response (fragment):**

```json
{
  "fees": [
    {
      "currency": "AUD",
      "fee_method_u_type": "fixedAmount",
      "fee_type": "PERIODIC",
      "fixed_amount": {
        "amount": "5.00"
      },
      "name": "Monthly account fee",
      "discounts": [
        {
          "discount_method_u_type": "fixedAmount",
          "fixed_amount": {
            "amount": "2.50"
          }
        }
      ]
    }
  ]
}
```

**Migrate:** Branch on `fee_method_u_type` and `discount_method_u_type`, read
from nested objects, and revisit strict `fee_type` handling.

GET /banking/accounts - features changes [#get-bankingaccounts---features-changes]

In `v2`, **is\_activated** on a feature is a **string enum** (for example
`ACTIVATED`), not a JSON boolean. Other feature fields stay on the same paths.

| v1                     | v2                         | Notes                      |
| ---------------------- | -------------------------- | -------------------------- |
| `is_activated` boolean | `is_activated` string enum | Type and validation change |

**Example v2 response (fragment):**

```json
{
  "features": [
    {
      "additional_info": "See, track and easily pay your bills online in NetBank or on the go in the CommBank app.",
      "additional_info_uri": "https://www.commbank.com.au/digital-banking/bpay-view.html",
      "additional_value": "BPAY View",
      "feature_type": "BILL_PAYMENT",
      "is_activated": "ACTIVATED"
    }
  ]
}
```

**Migrate:** Parse `is_activated` as a string and map allowed enum values
instead of `true` / `false`.

***

GET /banking/transactions — extended_data changes [#get-bankingtransactions--extended_data-changes]

In v2, old X2P1.01 fields at the root level are removed, and related fields
are now grouped under `extended_data.npp_payload`.

| v1                    | v2            | Notes                                                       |
| --------------------- | ------------- | ----------------------------------------------------------- |
| `nppPayload`          | `npp_payload` | Key renamed from camelCase to snake\_case                   |
| `service`             | removed       | Removed from `extended_data` root                           |
| `x2p101_payload`      | removed       | Removed from `extended_data` root                           |
| split field locations | grouped       | Related fields now appear under `extended_data.npp_payload` |

**Example v2 response:**

```json
{
  "extended_data": {
    "extension_u_type": "nppPayload",
    "payee": "Alice",
    "npp_payload": {
      "extended_description": "Alphashare transfer",
      "service": "X2P1",
      "service_version": "04"
    }
  }
}
```

**Migrate:** Rename `nppPayload` -> `npp_payload`. Stop reading root-level
`service` and `x2p101_payload`. In `v2`, fields like `service` and
`service_version` are provided under `extended_data.npp_payload`.

***

GET /common/identity — customer field removed [#get-commonidentity--customer-field-removed]

In `v1`, the response includes both `customer` (deprecated) and `identities`.
In `v2`, `customer` is removed and `identities` remains unchanged.

| v1                      | v2                                  |
| ----------------------- | ----------------------------------- |
| `response.customer`     | removed                             |
| `response.identities[]` | `response.identities[]` (unchanged) |

**Migrate:** Stop reading `response.customer`. Use
`response.identities[]` as the canonical identity list.

4. Reference [#4-reference]

**Version switcher in docs:** Toggle between `v1` and `v2` 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](/data-api/guides/core-concepts/versioning).

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


---

# Accounts (/data-api/api-reference/accounts)

List and retrieve bank account information from the Fiskil API.



The Accounts endpoint allows you to retrieve bank account information for an end user who has granted consent.

Endpoints [#endpoints]

| Method | Endpoint       | Description                       |
| ------ | -------------- | --------------------------------- |
| `GET`  | `/v1/accounts` | List all accounts for an end user |

The Account Model [#the-account-model]

| Attribute          | Type    | Description                                                   |
| ------------------ | ------- | ------------------------------------------------------------- |
| `id`               | string  | Unique identifier for the account                             |
| `account_number`   | string  | The account number (may be masked)                            |
| `bsb`              | string  | Bank-State-Branch number                                      |
| `name`             | string  | Account name or nickname                                      |
| `product_name`     | string  | Name of the bank product                                      |
| `product_category` | string  | Category of the product (e.g., TRANS\_AND\_SAVINGS\_ACCOUNTS) |
| `institution_id`   | string  | ID of the institution holding the account                     |
| `consent_id`       | string  | ID of the consent granting access to this account             |
| `is_owned`         | boolean | Whether the end user is the owner of the account              |
| `open_status`      | string  | Account status (OPEN, CLOSED)                                 |
| `creation_date`    | string  | When the account was created                                  |

Example Response [#example-response]

```json
{
  "id": "acc_123456789",
  "account_number": "****1234",
  "bsb": "123-456",
  "name": "Everyday Account",
  "product_name": "Complete Freedom Account",
  "product_category": "TRANS_AND_SAVINGS_ACCOUNTS",
  "institution_id": "22",
  "consent_id": "94549a73-a554-4b76-b824-d96898829751",
  "is_owned": true,
  "open_status": "OPEN",
  "creation_date": "2020-01-15"
}
```

List All Accounts [#list-all-accounts]

Retrieve all bank accounts for an end user.

```
GET https://api.fiskil.com/v1/accounts
```

Query Parameters [#query-parameters]

| Parameter          | Type    | Required | Description                             |
| ------------------ | ------- | -------- | --------------------------------------- |
| `end_user_id`      | string  | Yes      | The ID of the end user                  |
| `institution_id`   | string  | No       | Filter by institution ID                |
| `product_category` | string  | No       | Filter by product category              |
| `open_status`      | string  | No       | Filter by open status (OPEN, CLOSED)    |
| `limit`            | integer | No       | Maximum number of results (default: 25) |
| `offset`           | integer | No       | Number of results to skip               |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/accounts?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/accounts?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const accounts = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/accounts',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    accounts = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "acc_123456789",
      "account_number": "****1234",
      "bsb": "123-456",
      "name": "Everyday Account",
      "product_name": "Complete Freedom Account",
      "product_category": "TRANS_AND_SAVINGS_ACCOUNTS",
      "institution_id": "22",
      "consent_id": "94549a73-a554-4b76-b824-d96898829751",
      "is_owned": true,
      "open_status": "OPEN",
      "creation_date": "2020-01-15"
    },
    {
      "id": "acc_987654321",
      "account_number": "****5678",
      "bsb": "123-456",
      "name": "Savings Account",
      "product_name": "Goal Saver",
      "product_category": "TRANS_AND_SAVINGS_ACCOUNTS",
      "institution_id": "22",
      "consent_id": "94549a73-a554-4b76-b824-d96898829751",
      "is_owned": true,
      "open_status": "OPEN",
      "creation_date": "2020-03-20"
    }
  ],
  "links": {
    "next": "https://api.fiskil.com/v1/accounts?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5&offset=25"
  }
}
```

Product Categories [#product-categories]

Common product categories you may encounter:

| Category                     | Description                      |
| ---------------------------- | -------------------------------- |
| `TRANS_AND_SAVINGS_ACCOUNTS` | Transaction and savings accounts |
| `CRED_AND_CHRG_CARDS`        | Credit and charge cards          |
| `TERM_DEPOSITS`              | Term deposits                    |
| `PERS_LOANS`                 | Personal loans                   |
| `MARGIN_LOANS`               | Margin loans                     |
| `LEASES`                     | Leases                           |
| `TRADE_FINANCE`              | Trade finance accounts           |
| `REGULATED_TRUST_ACCOUNTS`   | Regulated trust accounts         |
| `RESIDENTIAL_MORTGAGES`      | Residential mortgages            |
| `BUSINESS_LOANS`             | Business loans                   |
| `OVERDRAFTS`                 | Overdraft facilities             |

Related Endpoints [#related-endpoints]

* [Balance](/data-api/api-reference/balance) - Get the balance for accounts
* [Transactions](/data-api/api-reference/getBankingTransactions) - Get transaction history for accounts


---

# Auth Session (/data-api/api-reference/auth-session)

Create authorization sessions for end users to grant data access.



An Auth Session is a single-use session for an end user to authorize data sharing from an institution. It generates a unique URL where users can complete the consent flow.

Endpoints [#endpoints]

| Method | Endpoint           | Description               |
| ------ | ------------------ | ------------------------- |
| `POST` | `/v1/auth/session` | Create a new auth session |

The Auth Session Model [#the-auth-session-model]

| Attribute    | Type    | Required | Description                                                           |
| ------------ | ------- | -------- | --------------------------------------------------------------------- |
| `id`         | string  | Yes      | The client ID                                                         |
| `session_id` | string  | Yes      | The unique session identifier                                         |
| `auth_url`   | string  | Yes      | The URL where the user should be redirected to complete authorization |
| `expires_at` | integer | Yes      | Unix timestamp when the auth session expires                          |

Example Response [#example-response]

```json
{
  "id": "5qcql2s0bn9qfh1m5qd1sl4gth",
  "session_id": "ea564d-56012s4-6ds4564",
  "auth_url": "https://auth.fiskil.com/redirect-url",
  "expires_at": 1621083785
}
```

Create Auth Session [#create-auth-session]

Create a new session for the authentication flow.

```
POST https://api.fiskil.com/v1/auth/session
```

Request Body [#request-body]

| Parameter        | Type   | Required    | Description                                                                                                                                                                                          |
| ---------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `end_user_id`    | string | Yes         | The ID of the end user to create the session for                                                                                                                                                     |
| `redirect_uri`   | string | Conditional | URL to redirect to after successful authorization. Required for the [redirect flow](#redirect-flow); can be omitted when using the [Link SDK](/data-api/guides/link-widget/integrating-the-link-sdk) |
| `cancel_uri`     | string | Conditional | URL to redirect to if the user cancels. Required for the [redirect flow](#redirect-flow); can be omitted when using the [Link SDK](/data-api/guides/link-widget/integrating-the-link-sdk)            |
| `institution_id` | string | No          | Pre-select a specific institution                                                                                                                                                                    |
| `permissions`    | array  | No          | Specific permissions to request                                                                                                                                                                      |

<Callout type="warn">
  `redirect_uri` and `cancel_uri` are only optional when the session is used with the Fiskil Link SDK, which handles callbacks in-app. If you're redirecting users to the Fiskil-hosted consent UI directly (the [redirect flow](#redirect-flow)) rather than embedding the Link SDK, omitting these fields will cause the request to fail.
</Callout>

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request POST \
      --url https://api.fiskil.com/v1/auth/session \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8' \
      --header 'content-type: application/json; charset=UTF-8' \
      --data '{
        "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
        "redirect_uri": "https://yourapp.com/callback",
        "cancel_uri": "https://yourapp.com/cancel"
      }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch('https://api.fiskil.com/v1/auth/session', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer {access_token}',
        'accept': 'application/json; charset=UTF-8',
        'content-type': 'application/json; charset=UTF-8'
      },
      body: JSON.stringify({
        end_user_id: '482c0e2b-5866-46b1-b795-220b7bba45b5',
        redirect_uri: 'https://yourapp.com/callback',
        cancel_uri: 'https://yourapp.com/cancel'
      })
    });

    const session = await response.json();
    console.log(session.auth_url);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.post(
        'https://api.fiskil.com/v1/auth/session',
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8',
            'content-type': 'application/json; charset=UTF-8'
        },
        json={
            'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5',
            'redirect_uri': 'https://yourapp.com/callback',
            'cancel_uri': 'https://yourapp.com/cancel'
        }
    )

    session = response.json()
    print(session['auth_url'])
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "id": "5qcql2s0bn9qfh1m5qd1sl4gth",
  "session_id": "ea564d-56012s4-6ds4564",
  "auth_url": "https://auth.fiskil.com/consent?session=ea564d-56012s4-6ds4564",
  "expires_at": 1621083785
}
```

Using the Auth Session [#using-the-auth-session]

After creating an auth session, redirect the user to the `auth_url`:

```javascript
// Redirect to Fiskil's authorization page
window.location.href = session.auth_url;
```

The user will then:

1. Select their institution (bank or energy provider)
2. Log in to their institution
3. Select which accounts to share
4. Confirm the consent

Handling Callbacks [#handling-callbacks]

**Success Callback**

When the user successfully completes authorization, they are redirected to your `redirect_uri` with the session information:

```
https://yourapp.com/callback?session_id=ea564d-56012s4-6ds4564
```

**Cancel/Error Callback**

If the user cancels or an error occurs, they are redirected to your `cancel_uri` with error details:

```
https://yourapp.com/cancel?error=access_denied&error_type=CONSENT_ENDUSER_DENIED&error_description=User+cancelled+the+flow
```

See [Errors](/data-api/api-reference/errors) for a complete list of error types.

Session Expiration [#session-expiration]

Auth sessions expire after a short period (typically 10-15 minutes). If a session expires before the user completes authorization, you'll need to create a new session.

<Callout type="info">
  Auth sessions are single-use. Once used (whether successfully or not), a new session must be created for subsequent authorization attempts.
</Callout>

Integration Patterns [#integration-patterns]

Redirect Flow [#redirect-flow]

The standard flow where users are redirected to the Fiskil-hosted consent UI:

```javascript
// Create session
const session = await createAuthSession(endUserId);

// Store session_id for callback verification
sessionStorage.setItem('fiskil_session', session.session_id);

// Redirect user
window.location.href = session.auth_url;
```

Popup Flow [#popup-flow]

Open the consent flow in a popup window:

```javascript
const session = await createAuthSession(endUserId);

const popup = window.open(
  session.auth_url,
  'FiskilConsent',
  'width=500,height=700,menubar=no,toolbar=no'
);

// Monitor for popup close or completion
const checkPopup = setInterval(() => {
  if (popup.closed) {
    clearInterval(checkPopup);
    // Handle completion or cancellation
  }
}, 500);
```

Embedded Flow (iframe) [#embedded-flow-iframe]

Embed the consent flow within your application:

```html
<iframe
  id="fiskil-consent"
  src="{auth_url}"
  width="100%"
  height="600"
  allow="payment"
></iframe>

<script>
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://auth.fiskil.com') return;
  
  if (event.data.type === 'consent_complete') {
    // Handle successful consent
  } else if (event.data.type === 'consent_error') {
    // Handle error
  }
});
</script>
```

Best Practices [#best-practices]

1. **Store Session ID**: Always store the `session_id` so you can verify the callback is legitimate.

2. **Handle Expiration**: Create a new session if the user returns after the session has expired.

3. **Pre-select Institution**: If you know which institution the user wants to connect, pass the `institution_id` to skip the selection step.

4. **Configure Redirect URIs**: Ensure your redirect and cancel URIs are configured in the Fiskil Console.


---

# Authentication (/data-api/api-reference/authentication)

Learn how to authenticate your API requests with Fiskil.



Fiskil uses client-based authentication to secure API access. To interact with our APIs, you'll need a `client_id` and `client_secret`. You can generate and manage these credentials directly from the Fiskil Developer Console.

Authentication Endpoint [#authentication-endpoint]

```
POST https://api.fiskil.com/v1/token
```

Authenticating Your API Requests [#authenticating-your-api-requests]

All API requests must include your `client_id` and `client_secret` in the request body.

<Callout type="warning">
  **Important:** All requests must be made over HTTPS. Any attempts to connect via HTTP will be automatically rejected to ensure your data remains secure.
</Callout>

Request Parameters [#request-parameters]

| Parameter       | Type   | Required | Description                                                      |
| --------------- | ------ | -------- | ---------------------------------------------------------------- |
| `client_id`     | string | Yes      | The generated client\_id associated with your Team's API key     |
| `client_secret` | string | Yes      | The generated client\_secret associated with your Team's API key |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request POST \
      --url https://api.fiskil.com/v1/token \
      --header 'accept: application/json; charset=UTF-8' \
      --header 'content-type: application/json; charset=UTF-8' \
      --data '{
        "client_id": "{client_id}",
        "client_secret": "{client_secret}"
      }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch('https://api.fiskil.com/v1/token', {
      method: 'POST',
      headers: {
        'accept': 'application/json; charset=UTF-8',
        'content-type': 'application/json; charset=UTF-8'
      },
      body: JSON.stringify({
        client_id: '{client_id}',
        client_secret: '{client_secret}'
      })
    });

    const data = await response.json();
    console.log(data.token);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.post(
        'https://api.fiskil.com/v1/token',
        headers={
            'accept': 'application/json; charset=UTF-8',
            'content-type': 'application/json; charset=UTF-8'
        },
        json={
            'client_id': '{client_id}',
            'client_secret': '{client_secret}'
        }
    )

    data = response.json()
    print(data['token'])
    ```
  </Tab>
</Tabs>

Example Response [#example-response]

```json
{
  "token": "yMWExMjJhLWEwZGQtNDVmYi1hMWY3LWMzODE4NmI3NmNyMWExMjJhLWEwZGQtNDVmYi1hMWY3LWMzODE4NmI3NmNjZCIsIlRva2VuVVVJRCI6ImUwMmUyMmFmLWUxMDMtNGU1OS1hNjViLWQyZGQwYWY5MGVhZSIsIktleUlEIjoiZmMwYjQyNGUtZWYxNC00MTA4LWIwMTQtZDRkOWI5ZjU4ZmVlIiwiZXhwIjoxNjIxMDgzNzg1LCJpYXQiOjE2MjEwODMxODVgd7QI7_O18P9gfCuEUnKjS0BJw4kb9ul_aFUPTWt0UcZTFwND_X4KcM7Es_eLSkKem7NM_63rhghzBofH7POsQ",
  "expires_in": 900
}
```

Using the Access Token [#using-the-access-token]

Once authenticated, include the token in the `Authorization` header for all subsequent API requests:

```bash
curl --request GET \
  --url https://api.fiskil.com/v1/end-users \
  --header 'Authorization: Bearer {access_token}' \
  --header 'accept: application/json; charset=UTF-8'
```

Keeping Your Credentials Secure [#keeping-your-credentials-secure]

Your `client_id` and `client_secret` are the keys to your account, so treat them with care. Here are a few best practices to help keep them safe:

* Never hardcode your credentials in your source code.
* Avoid storing them in public or private version control systems (like GitHub, even in private repos).
* Use environment variables or a secure secrets management system (like AWS Secrets Manager or HashiCorp Vault).
* Rotate your `client_secret` regularly and immediately if you suspect any compromise.

<Callout type="error">
  If your credentials are exposed or compromised, revoke them immediately from the Developer Console and generate new ones.
</Callout>

Token Expiration [#token-expiration]

Access tokens expire after the time specified in `expires_in` (in seconds). When your token expires, you'll need to re-authenticate to obtain a new one.

Typical token lifetime is **900 seconds (15 minutes)**.


---

# Balance (/data-api/api-reference/balance)

Get bank account balances from the Fiskil API.



The Balance endpoint allows you to retrieve the current balance information for an end user's bank accounts.

Endpoints [#endpoints]

| Method | Endpoint       | Description                             |
| ------ | -------------- | --------------------------------------- |
| `GET`  | `/v1/balances` | Get balances for an end user's accounts |

The Balance Model [#the-balance-model]

| Attribute           | Type   | Description                                 |
| ------------------- | ------ | ------------------------------------------- |
| `account_id`        | string | ID of the account                           |
| `current_balance`   | number | Current balance of the account              |
| `available_balance` | number | Available balance (may differ from current) |
| `credit_limit`      | number | Credit limit (for credit accounts)          |
| `currency`          | string | Currency code (e.g., AUD)                   |
| `as_of`             | string | Timestamp when the balance was last updated |

Example Response [#example-response]

```json
{
  "account_id": "acc_123456789",
  "current_balance": 5432.10,
  "available_balance": 5432.10,
  "credit_limit": null,
  "currency": "AUD",
  "as_of": "2023-01-15T10:30:00Z"
}
```

Get Balances [#get-balances]

Retrieve balance information for an end user's accounts.

```
GET https://api.fiskil.com/v1/balances
```

Query Parameters [#query-parameters]

| Parameter        | Type   | Required | Description                   |
| ---------------- | ------ | -------- | ----------------------------- |
| `end_user_id`    | string | Yes      | The ID of the end user        |
| `account_id`     | string | No       | Filter by specific account ID |
| `institution_id` | string | No       | Filter by institution ID      |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/balances?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/balances?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const balances = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/balances',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    balances = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "account_id": "acc_123456789",
      "current_balance": 5432.10,
      "available_balance": 5432.10,
      "credit_limit": null,
      "currency": "AUD",
      "as_of": "2023-01-15T10:30:00Z"
    },
    {
      "account_id": "acc_987654321",
      "current_balance": 12500.00,
      "available_balance": 12500.00,
      "credit_limit": null,
      "currency": "AUD",
      "as_of": "2023-01-15T10:30:00Z"
    },
    {
      "account_id": "acc_credit_001",
      "current_balance": -1250.50,
      "available_balance": 3749.50,
      "credit_limit": 5000.00,
      "currency": "AUD",
      "as_of": "2023-01-15T10:30:00Z"
    }
  ]
}
```

Understanding Balances [#understanding-balances]

Current vs Available Balance [#current-vs-available-balance]

* **Current Balance**: The actual balance on the account, including pending transactions
* **Available Balance**: The amount actually available to spend, which may be less than the current balance due to holds or pending transactions

Credit Accounts [#credit-accounts]

For credit cards and other credit accounts:

* **Current Balance**: Amount owed (typically shown as negative)
* **Available Balance**: Remaining credit available
* **Credit Limit**: Maximum credit extended on the account

Related Endpoints [#related-endpoints]

* [Accounts](/data-api/api-reference/accounts) - Get account details
* [Transactions](/data-api/api-reference/getBankingTransactions) - Get transaction history


---

# Billing (/data-api/api-reference/billing)

Get billing information from the Fiskil API.



The Billing endpoint provides billing transaction history for energy accounts.

Endpoints [#endpoints]

| Method | Endpoint      | Description                      |
| ------ | ------------- | -------------------------------- |
| `GET`  | `/v1/billing` | Get billing data for an end user |

The Billing Model [#the-billing-model]

| Attribute        | Type   | Description                                   |
| ---------------- | ------ | --------------------------------------------- |
| `account_id`     | string | ID of the energy account                      |
| `transaction_id` | string | Unique billing transaction ID                 |
| `type`           | string | Transaction type (USAGE, PAYMENT, ADJUSTMENT) |
| `amount`         | number | Transaction amount                            |
| `currency`       | string | Currency code                                 |
| `date`           | string | Transaction date                              |
| `description`    | string | Description of the transaction                |

Example Response [#example-response]

```json
{
  "account_id": "energy_acc_123",
  "transaction_id": "bill_txn_456",
  "type": "USAGE",
  "amount": -185.50,
  "currency": "AUD",
  "date": "2023-01-15",
  "description": "Electricity usage charges - December 2022"
}
```

Get Billing Data [#get-billing-data]

Retrieve billing information for an end user's energy accounts.

```
GET https://api.fiskil.com/v1/billing
```

Query Parameters [#query-parameters]

| Parameter     | Type    | Required | Description                   |
| ------------- | ------- | -------- | ----------------------------- |
| `end_user_id` | string  | Yes      | The ID of the end user        |
| `account_id`  | string  | No       | Filter by specific account ID |
| `from_date`   | string  | No       | Start date (YYYY-MM-DD)       |
| `to_date`     | string  | No       | End date (YYYY-MM-DD)         |
| `page[size]`  | integer | No       | Number of results (max 1000)  |
| `page[after]` | string  | No       | Cursor for pagination         |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/billing?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/billing?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const billing = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/billing',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    billing = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "account_id": "energy_acc_123",
      "transaction_id": "bill_txn_456",
      "type": "USAGE",
      "amount": -185.50,
      "currency": "AUD",
      "date": "2023-01-15",
      "description": "Electricity usage charges - December 2022"
    },
    {
      "account_id": "energy_acc_123",
      "transaction_id": "bill_txn_457",
      "type": "PAYMENT",
      "amount": 200.00,
      "currency": "AUD",
      "date": "2023-01-20",
      "description": "Payment received - Thank you"
    }
  ],
  "links": {
    "next": "https://api.fiskil.com/v1/billing?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5&page[after]=abc123"
  }
}
```

Transaction Types [#transaction-types]

| Type         | Description                  |
| ------------ | ---------------------------- |
| `USAGE`      | Energy usage charges         |
| `PAYMENT`    | Payment received             |
| `ADJUSTMENT` | Billing adjustment or credit |
| `FEE`        | Fees and charges             |
| `CONCESSION` | Concession discount applied  |

Related Endpoints [#related-endpoints]

* [Energy Accounts](/data-api/api-reference/energy-accounts) - Get account details
* [Energy Balances](/data-api/api-reference/energy-balances) - Get current balance
* [Invoices](/data-api/api-reference/invoices) - Get invoice documents


---

# Concessions (/data-api/api-reference/concessions)

Get concession information from the Fiskil API.



The Concessions endpoint provides information about concessions and discounts applied to energy accounts.

Endpoints [#endpoints]

| Method | Endpoint          | Description                     |
| ------ | ----------------- | ------------------------------- |
| `GET`  | `/v1/concessions` | Get concessions for an end user |

The Concession Model [#the-concession-model]

| Attribute      | Type   | Description                              |
| -------------- | ------ | ---------------------------------------- |
| `id`           | string | Unique concession identifier             |
| `account_id`   | string | Associated energy account ID             |
| `type`         | string | Type of concession                       |
| `display_name` | string | Display name of the concession           |
| `start_date`   | string | When the concession started              |
| `end_date`     | string | When the concession ends (if applicable) |
| `percentage`   | number | Percentage discount (if applicable)      |
| `fixed_amount` | number | Fixed amount discount (if applicable)    |

Example Response [#example-response]

```json
{
  "id": "conc_123",
  "account_id": "energy_acc_123",
  "type": "GOVERNMENT",
  "display_name": "Low Income Household Rebate",
  "start_date": "2023-01-01",
  "end_date": null,
  "percentage": null,
  "fixed_amount": 285.00
}
```

Get Concessions [#get-concessions]

Retrieve concession information for an end user's energy accounts.

```
GET https://api.fiskil.com/v1/concessions
```

Query Parameters [#query-parameters]

| Parameter     | Type    | Required | Description                   |
| ------------- | ------- | -------- | ----------------------------- |
| `end_user_id` | string  | Yes      | The ID of the end user        |
| `account_id`  | string  | No       | Filter by specific account ID |
| `page[size]`  | integer | No       | Number of results (max 1000)  |
| `page[after]` | string  | No       | Cursor for pagination         |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/concessions?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/concessions?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const concessions = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/concessions',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    concessions = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "conc_123",
      "account_id": "energy_acc_123",
      "type": "GOVERNMENT",
      "display_name": "Low Income Household Rebate",
      "start_date": "2023-01-01",
      "end_date": null,
      "percentage": null,
      "fixed_amount": 285.00
    },
    {
      "id": "conc_456",
      "account_id": "energy_acc_123",
      "type": "RETAILER",
      "display_name": "Pay On Time Discount",
      "start_date": "2023-01-01",
      "end_date": "2024-01-01",
      "percentage": 10,
      "fixed_amount": null
    }
  ]
}
```

Concession Types [#concession-types]

| Type         | Description                                           |
| ------------ | ----------------------------------------------------- |
| `GOVERNMENT` | Government-issued concession (e.g., pensioner rebate) |
| `RETAILER`   | Retailer-offered discount                             |
| `HARDSHIP`   | Hardship program discount                             |
| `LOYALTY`    | Customer loyalty discount                             |

Related Endpoints [#related-endpoints]

* [Energy Accounts](/data-api/api-reference/energy-accounts) - Get account details
* [Billing](/data-api/api-reference/billing) - See concessions applied to bills


---

# Consents (/data-api/api-reference/consents)

View and manage data sharing consents in the Fiskil API.



A Consent represents the access period and scope of data an End User allows your application to access. Fiskil handles a lot of the compliance requirements around consents, but you should also alert your customers about their consents. These APIs will help you embed an end user's personalized consents into your application.

Endpoints [#endpoints]

| Method   | Endpoint                       | Description                       |
| -------- | ------------------------------ | --------------------------------- |
| `GET`    | `/v1/consent`                  | List all consents for an end user |
| `DELETE` | `/v1/consent/{arrangement_id}` | Revoke a consent                  |

The Consent Model [#the-consent-model]

| Attribute            | Type    | Required | Description                                                 |
| -------------------- | ------- | -------- | ----------------------------------------------------------- |
| `arrangement_id`     | string  | Yes      | CDR arrangement ID provided by the data holder              |
| `active`             | boolean | Yes      | Indicates whether consent is active                         |
| `app_name`           | string  | Yes      | Your application name                                       |
| `app_logo`           | string  | Yes      | URL to your application logo                                |
| `created_at`         | string  | Yes      | When the consent was created (ISO 8601)                     |
| `duration`           | integer | Yes      | The time period access was granted, in seconds              |
| `end_user_id`        | string  | Yes      | ID of the end user that authorized the consent              |
| `end_user_email`     | string  | Yes      | End user's email                                            |
| `expires_at`         | string  | Yes      | When the consent expires (ISO 8601)                         |
| `institution_id`     | string  | Yes      | The identifier for the institution the consent is held with |
| `institution_name`   | string  | Yes      | Institution name                                            |
| `institution_logo`   | string  | Yes      | Institution logo URL                                        |
| `institution_type`   | string  | Yes      | Institution type (e.g., "banking", "energy")                |
| `last_accessed`      | string  | Yes      | The last time the consent was used to access data           |
| `last_consent`       | string  | Yes      | The last time the consent was acknowledged by the end user  |
| `permissions`        | array   | Yes      | A list of the data permissions granted                      |
| `termination_reason` | string  | Yes      | Reason for consent termination (if applicable)              |

Example Response [#example-response]

```json
{
  "active": true,
  "app_logo": "https://acme.com/app-logo.png",
  "app_name": "MyCoolApp",
  "arrangement_id": "94549a73-a554-4b76-b824-d96898829751",
  "created_at": "2021-03-18T02:46:42Z",
  "duration": 7776000,
  "end_user_email": "tony.stark@example.com",
  "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
  "expires_at": "2023-01-01T10:42:40Z",
  "institution_id": "11",
  "institution_logo": "https://example.com/images/gringotts-logo.png",
  "institution_name": "Gringotts",
  "institution_type": "banking",
  "last_accessed": "2023-01-02T10:42:42Z",
  "last_consent": "2023-01-01T10:42:40Z",
  "permissions": [
    "accounts",
    "balances",
    "transactions"
  ],
  "termination_reason": "Expired or Revoked"
}
```

List Consents [#list-consents]

Retrieve all consents for a specific end user.

```
GET https://api.fiskil.com/v1/consent
```

Query Parameters [#query-parameters]

| Parameter     | Type    | Required | Description                                                          |
| ------------- | ------- | -------- | -------------------------------------------------------------------- |
| `end_user_id` | string  | No       | The ID of the end user to list consents for                          |
| `active`      | boolean | No       | Filter to include only active or inactive (revoked/expired) consents |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/consent?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5&active=true' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/consent?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5&active=true',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const consents = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/consent',
        params={
            'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5',
            'active': 'true'
        },
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    consents = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
[
  {
    "active": true,
    "app_logo": "https://acme.com/app-logo.png",
    "app_name": "MyCoolApp",
    "arrangement_id": "94549a73-a554-4b76-b824-d96898829751",
    "created_at": "2021-03-18T02:46:42Z",
    "duration": 7776000,
    "end_user_email": "tony.stark@example.com",
    "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
    "expires_at": "2023-01-01T10:42:40Z",
    "institution_id": "11",
    "institution_logo": "https://example.com/images/gringotts-logo.png",
    "institution_name": "Gringotts",
    "institution_type": "banking",
    "last_accessed": "2023-01-02T10:42:42Z",
    "last_consent": "2023-01-01T10:42:40Z",
    "permissions": [
      "accounts",
      "balances",
      "transactions"
    ],
    "termination_reason": null
  }
]
```

Revoke Consent [#revoke-consent]

Revoke an active consent. This immediately terminates the end user's data sharing agreement.

```
DELETE https://api.fiskil.com/v1/consent/{arrangement_id}
```

Path Parameters [#path-parameters]

| Parameter        | Type   | Required | Description                                             |
| ---------------- | ------ | -------- | ------------------------------------------------------- |
| `arrangement_id` | string | Yes      | CDR arrangement ID as returned by the list consents API |

Example Request [#example-request-1]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request DELETE \
      --url https://api.fiskil.com/v1/consent/94549a73-a554-4b76-b824-d96898829751 \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/consent/94549a73-a554-4b76-b824-d96898829751',
      {
        method: 'DELETE',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.delete(
        'https://api.fiskil.com/v1/consent/94549a73-a554-4b76-b824-d96898829751',
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )
    ```
  </Tab>
</Tabs>

<Callout type="warning">
  Revoking a consent is permanent. Once revoked, you will no longer be able to access the end user's data from that institution until they create a new consent.
</Callout>

Consent Lifecycle [#consent-lifecycle]

Consents follow a specific lifecycle:

1. **Created**: Consent is established when end user completes the authorization flow
2. **Active**: Consent is active and data can be accessed
3. **Expired**: Consent has passed its expiration date
4. **Revoked**: Consent has been manually revoked by you or the end user

Consent Duration [#consent-duration]

The `duration` field indicates how long the consent was granted for, in seconds. Common durations:

| Duration (seconds) | Human readable |
| ------------------ | -------------- |
| 86400              | 1 day          |
| 604800             | 1 week         |
| 2592000            | 30 days        |
| 7776000            | 90 days        |
| 31536000           | 1 year         |

Best Practices [#best-practices]

1. **Display Consents to Users**: Build a consent management UI that allows users to view and revoke their consents.

2. **Monitor Expiration**: Set up reminders or workflows to prompt users to re-consent before their consents expire.

3. **Handle Revocation Gracefully**: When a consent is revoked, update your application state accordingly and inform the user.

4. **Use Webhooks**: Subscribe to consent-related [webhooks](/data-api/guides/core-concepts/webhooks) to get real-time updates about consent status changes.


---

# DER (/data-api/api-reference/der)

Get Distributed Energy Resources (DER) data from the Fiskil API.



The DER (Distributed Energy Resources) endpoint provides information about solar panels, batteries, and other distributed energy resources at a service point.

Endpoints [#endpoints]

| Method | Endpoint  | Description                  |
| ------ | --------- | ---------------------------- |
| `GET`  | `/v1/der` | Get DER data for an end user |

The DER Model [#the-der-model]

| Attribute           | Type    | Description                         |
| ------------------- | ------- | ----------------------------------- |
| `service_point_id`  | string  | NMI/service point identifier        |
| `account_id`        | string  | Associated energy account ID        |
| `devices`           | array   | List of DER devices                 |
| `approved_capacity` | number  | Total approved export capacity (kW) |
| `available_phases`  | integer | Number of available phases          |

Device Object [#device-object]

| Attribute      | Type   | Description                                  |
| -------------- | ------ | -------------------------------------------- |
| `device_type`  | string | Type of device (SOLAR, BATTERY, EV\_CHARGER) |
| `manufacturer` | string | Device manufacturer                          |
| `model`        | string | Device model                                 |
| `capacity`     | number | Device capacity (kW)                         |
| `install_date` | string | Installation date                            |
| `status`       | string | Device status                                |

Example Response [#example-response]

```json
{
  "service_point_id": "NMI123456789",
  "account_id": "energy_acc_123",
  "approved_capacity": 5.0,
  "available_phases": 1,
  "devices": [
    {
      "device_type": "SOLAR",
      "manufacturer": "SunPower",
      "model": "X22-360",
      "capacity": 6.6,
      "install_date": "2022-03-15",
      "status": "ACTIVE"
    }
  ]
}
```

Get DER Data [#get-der-data]

Retrieve DER information for an end user's service points.

```
GET https://api.fiskil.com/v1/der
```

Query Parameters [#query-parameters]

| Parameter          | Type    | Required | Description                      |
| ------------------ | ------- | -------- | -------------------------------- |
| `end_user_id`      | string  | Yes      | The ID of the end user           |
| `service_point_id` | string  | No       | Filter by specific service point |
| `page[size]`       | integer | No       | Number of results (max 1000)     |
| `page[after]`      | string  | No       | Cursor for pagination            |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/der?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/der?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const der = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/der',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    der = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "service_point_id": "NMI123456789",
      "account_id": "energy_acc_123",
      "approved_capacity": 5.0,
      "available_phases": 1,
      "devices": [
        {
          "device_type": "SOLAR",
          "manufacturer": "SunPower",
          "model": "X22-360",
          "capacity": 6.6,
          "install_date": "2022-03-15",
          "status": "ACTIVE"
        },
        {
          "device_type": "BATTERY",
          "manufacturer": "Tesla",
          "model": "Powerwall 2",
          "capacity": 13.5,
          "install_date": "2022-03-15",
          "status": "ACTIVE"
        }
      ]
    }
  ]
}
```

Device Types [#device-types]

| Type         | Description              |
| ------------ | ------------------------ |
| `SOLAR`      | Solar PV system          |
| `BATTERY`    | Battery storage system   |
| `EV_CHARGER` | Electric vehicle charger |
| `WIND`       | Wind turbine             |

Use Cases [#use-cases]

* **Solar Monitoring**: Track solar installations
* **Battery Analysis**: Understand battery capacity and usage
* **EV Integration**: Identify EV charging infrastructure
* **Energy Trading**: Identify customers for VPP programs

Related Endpoints [#related-endpoints]

* [Service Points](/data-api/api-reference/service-points) - Get NMI details
* [Usage](/data-api/api-reference/usage) - Get energy usage including generation


---

# Direct Debits (/data-api/api-reference/direct-debits)

Get direct debit information from the Fiskil API.



The Direct Debits endpoint provides information about direct debit arrangements on an end user's accounts.

Endpoints [#endpoints]

| Method | Endpoint            | Description                       |
| ------ | ------------------- | --------------------------------- |
| `GET`  | `/v1/direct-debits` | Get direct debits for an end user |

The Direct Debit Model [#the-direct-debit-model]

| Attribute           | Type   | Description                              |
| ------------------- | ------ | ---------------------------------------- |
| `id`                | string | Unique identifier for the direct debit   |
| `account_id`        | string | ID of the account the direct debit is on |
| `authorised_entity` | string | Name of the entity authorized to debit   |
| `last_debit_date`   | string | Date of the last debit                   |
| `last_debit_amount` | number | Amount of the last debit                 |

Example Response [#example-response]

```json
{
  "id": "dd_123",
  "account_id": "acc_123456789",
  "authorised_entity": "Netflix Australia",
  "last_debit_date": "2023-01-15",
  "last_debit_amount": 22.99
}
```

Get Direct Debits [#get-direct-debits]

Retrieve direct debit information for an end user.

```
GET https://api.fiskil.com/v1/direct-debits
```

Query Parameters [#query-parameters]

| Parameter     | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `end_user_id` | string | Yes      | The ID of the end user        |
| `account_id`  | string | No       | Filter by specific account ID |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/direct-debits?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/direct-debits?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const directDebits = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/direct-debits',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    direct_debits = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "dd_123",
      "account_id": "acc_123456789",
      "authorised_entity": "Netflix Australia",
      "last_debit_date": "2023-01-15",
      "last_debit_amount": 22.99
    },
    {
      "id": "dd_456",
      "account_id": "acc_123456789",
      "authorised_entity": "Spotify",
      "last_debit_date": "2023-01-10",
      "last_debit_amount": 11.99
    }
  ]
}
```

Use Cases [#use-cases]

* **Subscription Detection**: Identify recurring subscriptions for budgeting apps
* **Bill Management**: Help users track and manage their regular payments
* **Affordability Assessment**: Understand recurring financial commitments

Related Endpoints [#related-endpoints]

* [Accounts](/data-api/api-reference/accounts) - Get account details
* [Transactions](/data-api/api-reference/getBankingTransactions) - See the actual debit transactions
* [Scheduled Payments](/data-api/api-reference/scheduled-payments) - Get scheduled payments


---

# End User (/data-api/api-reference/end-user)

Manage end users in your Fiskil application.



An End User represents your user in the Fiskil platform. End users are used for linking accounts and accessing data. You'll need to create an end user before they can authorize access to their accounts.

Endpoints [#endpoints]

| Method   | Endpoint             | Description           |
| -------- | -------------------- | --------------------- |
| `GET`    | `/v1/end-users`      | Get end user by email |
| `POST`   | `/v1/end-users`      | Create a new end user |
| `DELETE` | `/v1/end-users/{id}` | Delete an end user    |
| `GET`    | `/v1/end-users/{id}` | Get end user by ID    |

The End User Model [#the-end-user-model]

| Attribute | Type   | Required | Description                                                                        |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `id`      | string | Yes      | A unique identifier for the End User object                                        |
| `email`   | string | No       | The end user's email address. Used for notifying the end user about their consents |
| `name`    | string | No       | The end user's name                                                                |
| `phone`   | string | No       | The end user's phone number. Used for notifying the end user about their consents  |

Example Response [#example-response]

```json
{
  "id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
  "email": "john_starmer@gmail.com",
  "name": "John Starmer",
  "phone": "+614123456789"
}
```

Get End User by Email [#get-end-user-by-email]

Retrieve an end user using their email address.

```
GET https://api.fiskil.com/v1/end-users
```

Query Parameters [#query-parameters]

| Parameter | Type   | Required | Description                          |
| --------- | ------ | -------- | ------------------------------------ |
| `email`   | string | No       | Email address to filter end users by |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/end-users?email=john@example.com' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/end-users?email=john@example.com',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const endUsers = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/end-users',
        params={'email': 'john@example.com'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    end_users = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
[
  {
    "id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
    "email": "john@example.com",
    "name": "John Starmer",
    "phone": "+614123456789"
  }
]
```

Add End User [#add-end-user]

Create a new end user for linking accounts.

```
POST https://api.fiskil.com/v1/end-users
```

Request Body [#request-body]

| Parameter | Type   | Required | Description                                                 |
| --------- | ------ | -------- | ----------------------------------------------------------- |
| `email`   | string | No       | The end user's email address                                |
| `name`    | string | No       | The end user's name                                         |
| `phone`   | string | No       | The end user's phone number in E.164 format                 |
| `abn`     | string | No       | Australian Business Number (ABN) if representing a business |

Example Request [#example-request-1]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request POST \
      --url https://api.fiskil.com/v1/end-users \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8' \
      --header 'content-type: application/json; charset=UTF-8' \
      --data '{
        "email": "john@example.com",
        "name": "John Doe",
        "phone": "+614123456789"
      }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch('https://api.fiskil.com/v1/end-users', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer {access_token}',
        'accept': 'application/json; charset=UTF-8',
        'content-type': 'application/json; charset=UTF-8'
      },
      body: JSON.stringify({
        email: 'john@example.com',
        name: 'John Doe',
        phone: '+614123456789'
      })
    });

    const result = await response.json();
    console.log(result.end_user_id);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.post(
        'https://api.fiskil.com/v1/end-users',
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8',
            'content-type': 'application/json; charset=UTF-8'
        },
        json={
            'email': 'john@example.com',
            'name': 'John Doe',
            'phone': '+614123456789'
        }
    )

    result = response.json()
    print(result['end_user_id'])
    ```
  </Tab>
</Tabs>

Example Response [#example-response-2]

```json
{
  "end_user_id": "83064af3-bb81-4514-a6d4-afba340825cd"
}
```

<Callout type="info">
  Store the `end_user_id` securely—you'll need it to create auth sessions and access data for this user.
</Callout>

Delete End User [#delete-end-user]

Delete an existing end user. This will also revoke all associated consents.

```
DELETE https://api.fiskil.com/v1/end-users/{id}
```

Path Parameters [#path-parameters]

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `id`      | string | Yes      | The ID of the end user to delete |

Example Request [#example-request-2]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request DELETE \
      --url https://api.fiskil.com/v1/end-users/482c0e2b-5866-46b1-b795-220b7bba45b5 \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/end-users/482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'DELETE',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.delete(
        'https://api.fiskil.com/v1/end-users/482c0e2b-5866-46b1-b795-220b7bba45b5',
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )
    ```
  </Tab>
</Tabs>

<Callout type="warning">
  Deleting an end user is permanent and will revoke all associated consents. This action cannot be undone.
</Callout>

Get End User by ID [#get-end-user-by-id]

Retrieve an end user by their ID.

```
GET https://api.fiskil.com/v1/end-users/{id}
```

Path Parameters [#path-parameters-1]

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `id`      | string | Yes      | The ID of the end user to fetch |

Example Request [#example-request-3]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url https://api.fiskil.com/v1/end-users/482c0e2b-5866-46b1-b795-220b7bba45b5 \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/end-users/482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const endUser = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/end-users/482c0e2b-5866-46b1-b795-220b7bba45b5',
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    end_user = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-3]

```json
{
  "id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
  "email": "john_starmer@gmail.com",
  "name": "John Starmer",
  "phone": "+614123456789"
}
```


---

# Energy Accounts (/data-api/api-reference/energy-accounts)

List and retrieve energy account information from the Fiskil API.



The Energy Accounts endpoint allows you to retrieve energy account information for an end user who has granted consent.

Endpoints [#endpoints]

| Method | Endpoint              | Description                              |
| ------ | --------------------- | ---------------------------------------- |
| `GET`  | `/v1/energy-accounts` | List all energy accounts for an end user |

The Energy Account Model [#the-energy-account-model]

| Attribute        | Type   | Description                       |
| ---------------- | ------ | --------------------------------- |
| `id`             | string | Unique identifier for the account |
| `account_number` | string | The account number                |
| `display_name`   | string | Display name for the account      |
| `creation_date`  | string | When the account was created      |
| `status`         | string | Account status (OPEN, CLOSED)     |
| `institution_id` | string | ID of the energy retailer         |
| `consent_id`     | string | ID of the consent granting access |
| `plans`          | array  | Associated energy plans           |

Example Response [#example-response]

```json
{
  "id": "energy_acc_123",
  "account_number": "12345678",
  "display_name": "Home Electricity",
  "creation_date": "2021-06-15",
  "status": "OPEN",
  "institution_id": "energy_retailer_1",
  "consent_id": "94549a73-a554-4b76-b824-d96898829751",
  "plans": [
    {
      "nickname": "Residential Saver",
      "service_point_ids": ["NMI123456789"]
    }
  ]
}
```

List Energy Accounts [#list-energy-accounts]

Retrieve all energy accounts for an end user.

```
GET https://api.fiskil.com/v1/energy-accounts
```

Query Parameters [#query-parameters]

| Parameter     | Type    | Required | Description                  |
| ------------- | ------- | -------- | ---------------------------- |
| `end_user_id` | string  | Yes      | The ID of the end user       |
| `page[size]`  | integer | No       | Number of results (max 1000) |
| `page[after]` | string  | No       | Cursor for pagination        |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/energy-accounts?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/energy-accounts?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const accounts = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/energy-accounts',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    accounts = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "energy_acc_123",
      "account_number": "12345678",
      "display_name": "Home Electricity",
      "creation_date": "2021-06-15",
      "status": "OPEN",
      "institution_id": "energy_retailer_1",
      "consent_id": "94549a73-a554-4b76-b824-d96898829751",
      "plans": [
        {
          "nickname": "Residential Saver",
          "service_point_ids": ["NMI123456789"]
        }
      ]
    }
  ],
  "links": {
    "next": "https://api.fiskil.com/v1/energy-accounts?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5&page[after]=abc123"
  }
}
```

Related Endpoints [#related-endpoints]

* [Energy Balances](/data-api/api-reference/energy-balances) - Get account balances
* [Usage](/data-api/api-reference/usage) - Get usage data
* [Service Points](/data-api/api-reference/service-points) - Get NMI information


---

# Energy Balances (/data-api/api-reference/energy-balances)

Get energy account balances from the Fiskil API.



The Energy Balances endpoint allows you to retrieve the current balance information for an end user's energy accounts.

Endpoints [#endpoints]

| Method | Endpoint              | Description                      |
| ------ | --------------------- | -------------------------------- |
| `GET`  | `/v1/energy-balances` | Get balances for energy accounts |

The Energy Balance Model [#the-energy-balance-model]

| Attribute    | Type   | Description                                           |
| ------------ | ------ | ----------------------------------------------------- |
| `account_id` | string | ID of the energy account                              |
| `balance`    | number | Current balance (positive = credit, negative = owing) |
| `currency`   | string | Currency code (AUD)                                   |
| `as_of`      | string | Timestamp when balance was last updated               |

Example Response [#example-response]

```json
{
  "account_id": "energy_acc_123",
  "balance": -245.50,
  "currency": "AUD",
  "as_of": "2023-01-15T10:30:00Z"
}
```

Get Energy Balances [#get-energy-balances]

Retrieve balance information for an end user's energy accounts.

```
GET https://api.fiskil.com/v1/energy-balances
```

Query Parameters [#query-parameters]

| Parameter     | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `end_user_id` | string | Yes      | The ID of the end user        |
| `account_id`  | string | No       | Filter by specific account ID |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/energy-balances?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/energy-balances?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const balances = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/energy-balances',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    balances = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "account_id": "energy_acc_123",
      "balance": -245.50,
      "currency": "AUD",
      "as_of": "2023-01-15T10:30:00Z"
    }
  ]
}
```

Understanding Energy Balances [#understanding-energy-balances]

* **Negative balance**: Amount owing to the energy retailer
* **Positive balance**: Credit on the account
* **Zero balance**: Account is paid in full

Related Endpoints [#related-endpoints]

* [Energy Accounts](/data-api/api-reference/energy-accounts) - Get account details
* [Billing](/data-api/api-reference/billing) - Get billing information
* [Invoices](/data-api/api-reference/invoices) - Get invoice data


---

# Errors (/data-api/api-reference/errors)

Understanding error responses from the Fiskil API.



Fiskil uses conventional HTTP response codes to indicate the success or failure of an API request.

* Codes in the **2xx** range indicate success.
* Codes in the **4xx** range indicate an issue with request parameters.
* Codes in the **5xx** range indicate an error with Fiskil's servers.

In case of 4xx or 5xx errors, Fiskil returns an error response object with the following attributes.

Error Response Object [#error-response-object]

| Attribute | Type   | Description                                                                                                                   |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`      | string | A unique ID associated with the error. Fiskil uses it to debug issues. Clients can send it to us in case of 5xx errors.       |
| `name`    | string | A short description of this error. This should be stable across multiple occurrences of this type of error.                   |
| `message` | string | A detailed description of this error. This should be considered unique to individual occurrences and is useful for debugging. |

Example Error Response [#example-error-response]

```json
{
  "id": "err_acde070d-8c4c-4f0d-9d8a-162843c10333",
  "name": "InvalidRequest",
  "message": "The end_user_id parameter is required"
}
```

<Callout type="info">
  Note that direct requests to data holders (with `cdr` in the request URL) will follow the error response convention as per CDR guidelines.
</Callout>

HTTP Status Codes [#http-status-codes]

| Code  | Description                                             |
| ----- | ------------------------------------------------------- |
| `200` | OK - Request succeeded                                  |
| `201` | Created - Resource created successfully                 |
| `400` | Bad Request - Invalid request parameters                |
| `401` | Unauthorized - Invalid or missing authentication        |
| `403` | Forbidden - Access denied                               |
| `404` | Not Found - Resource not found                          |
| `429` | Too Many Requests - Rate limit exceeded                 |
| `500` | Internal Server Error - Something went wrong on our end |

Error Types [#error-types]

The following are consent lifecycle related errors that may occur during consent creation:

AUTH_SESSION_INVALID [#auth_session_invalid]

This error originates from the Auth UI when it detects that the current authorisation session is invalid or has reached a terminal state. The Auth UI propagates this error to the parent window, so it only applies to embedded flows (iframe or popup).

**Example:**

```json
{
  "isCompleted": false,
  "error": "auth_session_invalid",
  "errorDescription": "Auth session is either terminated or not found.",
  "errorType": "AUTH_SESSION_INVALID",
  "errorURI": "https://docs.fiskil.com/errors#AUTH_SESSION_INVALID"
}
```

**Common Causes:**

* The provided `session_id` does not exist or cannot be found (invalid session)
* The authorisation session has expired, been terminated, or was already completed (terminal session)
* The embedded flow (iframe/popup) was initialised after the session moved to a terminal state

**Troubleshooting:**

* Verify the `session_id` is valid and active before loading the Auth UI
* Start a new authorisation session and re-initiate the flow
* For iframe/popup integrations, ensure the parent window listens for the posted message and handles it appropriately
* If the issue persists, raise a support ticket including `team_id` and `session_id` (or `error_id`)

***

AUTH_SESSION_CANCELLED [#auth_session_cancelled]

This error originates from the Fiskil Auth UI when the end-user explicitly cancels the authorisation session before or after being redirected to/from the remote institution's consent flow.

**Common Causes:**

* The end-user clicked Cancel on the Fiskil-hosted authorisation screen

**Troubleshooting:**

* Unlike `CONSENT_ENDUSER_DENIED`, this error cannot be retried. The user must restart the authorisation flow from the beginning—a new `auth_session_id` is required.

***

CONSENT_UPSTREAM_PROCESSING_ERROR [#consent_upstream_processing_error]

This error is returned by our API in the event of a remote institution's failure during consent creation by an end-user within the data holder's web application.

**Common Causes:**

* A non-recoverable application error occurred upstream in the remote institution's consent flow

**Troubleshooting:**

* Ask the user to retry the authorisation and complete the institution consent flow
* If the error persists after multiple attempts, raise a ticket in the Fiskil support issue tracking system

***

CONSENT_ENDUSER_DENIED [#consent_enduser_denied]

This error is returned by the API when the end-user aborts a consent creation flow within the remote institution consent authorisation.

**Common Causes:**

* The end-user clicks cancel during consent creation within the remote institution's consent flow

***

CONSENT_OTP_FAILURE [#consent_otp_failure]

This error is returned by the API when the end-user experiences OTP authorisation failure during a consent creation flow within the remote institution consent process.

**Common Causes:**

* The user entered an incorrect one-time password presented by the selected institution
* An OTP has been provided for a non-existing end-user email
* The end-user state is unauthenticated

**Troubleshooting:**

* Validate with the user that they are accessing the correct remote institution where they have an account
* The end-user should retry the authorisation and complete the institution consent flow
* The end-user should contact the institution directly to validate the status of their account and eligibility
* If the user still cannot log in despite providing correct information, submit a "Consent Failure" support ticket with: `team_id`, `session_id` or `error_id`, and `user_id`

***

CONSENT_ENDUSER_INELIGIBLE [#consent_enduser_ineligible]

This error is returned by the API when an authorised end-user fails to select a valid remote institution account during a consent authorisation.

**Common Causes:**

* The end-user not having access to a valid account
* The end-user not having pre-approval for an account
* In the scenario of a business account, the user not being a Nominated Representative for the account

**Troubleshooting:**

* Validate the user is accessing the correct institution where they hold a valid account
* Validate the user's account is an eligible account with the remote institution
* If the account is a business account, ensure your user has listed themselves as a Nominated Representative to share data
* The end-user should retry the authorisation and complete the institution consent flow

***

CONSENT_TIMEOUT [#consent_timeout]

This error is returned by the API when an authorised end-user fails to complete a consent flow before the data holder's web application experiences a timeout. Reasons include leaving the web application open for too long, or closing the browser window before completing the flow.

**Common Causes:**

* The user abandoned the consent authorisation flow without completing it
* Internet connection issues on the end-user device

**Troubleshooting:**

* The end-user should retry the authorisation and complete the institution consent flow


---

# Identity (/data-api/api-reference/identity)

Get identity information from the Fiskil API.



The Identity endpoint provides identity information about the account holder. This works for both banking and energy accounts.

Endpoints [#endpoints]

| Method | Endpoint       | Description                       |
| ------ | -------------- | --------------------------------- |
| `GET`  | `/v1/identity` | Get identity data for an end user |

The Identity Model [#the-identity-model]

| Attribute           | Type   | Description                          |
| ------------------- | ------ | ------------------------------------ |
| `end_user_id`       | string | ID of the end user                   |
| `type`              | string | Identity type (PERSON, ORGANISATION) |
| `first_name`        | string | First name (for PERSON)              |
| `last_name`         | string | Last name (for PERSON)               |
| `middle_names`      | array  | Middle names (for PERSON)            |
| `organisation_name` | string | Organisation name (for ORGANISATION) |
| `date_of_birth`     | string | Date of birth (for PERSON)           |
| `addresses`         | array  | List of addresses                    |
| `emails`            | array  | List of email addresses              |
| `phones`            | array  | List of phone numbers                |

Example Response [#example-response]

```json
{
  "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
  "type": "PERSON",
  "first_name": "John",
  "last_name": "Smith",
  "middle_names": ["William"],
  "organisation_name": null,
  "date_of_birth": "1985-06-15",
  "addresses": [
    {
      "type": "RESIDENTIAL",
      "street": "123 Example Street",
      "suburb": "Sydney",
      "state": "NSW",
      "postcode": "2000",
      "country": "AU"
    }
  ],
  "emails": [
    {
      "type": "PRIMARY",
      "address": "john.smith@example.com"
    }
  ],
  "phones": [
    {
      "type": "MOBILE",
      "number": "+61412345678"
    }
  ]
}
```

Get Identity Data [#get-identity-data]

Retrieve identity information for an end user.

```
GET https://api.fiskil.com/v1/identity
```

Query Parameters [#query-parameters]

| Parameter     | Type   | Required | Description                |
| ------------- | ------ | -------- | -------------------------- |
| `end_user_id` | string | Yes      | The ID of the end user     |
| `consent_id`  | string | No       | Filter by specific consent |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/identity?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/identity?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const identity = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/identity',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    identity = response.json()
    ```
  </Tab>
</Tabs>

Example Response (Person) [#example-response-person]

```json
{
  "data": [
    {
      "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
      "consent_id": "94549a73-a554-4b76-b824-d96898829751",
      "type": "PERSON",
      "first_name": "John",
      "last_name": "Smith",
      "middle_names": ["William"],
      "date_of_birth": "1985-06-15",
      "addresses": [
        {
          "type": "RESIDENTIAL",
          "street": "123 Example Street",
          "suburb": "Sydney",
          "state": "NSW",
          "postcode": "2000",
          "country": "AU"
        }
      ],
      "emails": [
        {
          "type": "PRIMARY",
          "address": "john.smith@example.com"
        }
      ],
      "phones": [
        {
          "type": "MOBILE",
          "number": "+61412345678"
        }
      ]
    }
  ]
}
```

Example Response (Organisation) [#example-response-organisation]

```json
{
  "data": [
    {
      "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
      "consent_id": "94549a73-a554-4b76-b824-d96898829751",
      "type": "ORGANISATION",
      "organisation_name": "ACME Corporation Pty Ltd",
      "abn": "12345678901",
      "addresses": [
        {
          "type": "BUSINESS",
          "street": "456 Business Ave",
          "suburb": "Melbourne",
          "state": "VIC",
          "postcode": "3000",
          "country": "AU"
        }
      ],
      "emails": [
        {
          "type": "PRIMARY",
          "address": "accounts@acme.com.au"
        }
      ],
      "phones": [
        {
          "type": "BUSINESS",
          "number": "+61398765432"
        }
      ]
    }
  ]
}
```

Identity Types [#identity-types]

| Type           | Description               |
| -------------- | ------------------------- |
| `PERSON`       | Individual account holder |
| `ORGANISATION` | Business or organisation  |

Address Types [#address-types]

| Type          | Description                 |
| ------------- | --------------------------- |
| `RESIDENTIAL` | Home address                |
| `MAILING`     | Postal/mailing address      |
| `BUSINESS`    | Business address            |
| `REGISTERED`  | Registered business address |

Phone Types [#phone-types]

| Type       | Description    |
| ---------- | -------------- |
| `MOBILE`   | Mobile phone   |
| `HOME`     | Home landline  |
| `BUSINESS` | Business phone |

Use Cases [#use-cases]

* **KYC Verification**: Verify customer identity
* **Pre-fill Forms**: Auto-fill application forms
* **Address Verification**: Confirm customer addresses
* **Contact Information**: Get up-to-date contact details

<Callout type="info">
  Identity information is subject to the permissions granted by the end user during consent. Not all fields may be available for all consents.
</Callout>

Related Endpoints [#related-endpoints]

* [Accounts](/data-api/api-reference/accounts) - Get bank account details
* [Energy Accounts](/data-api/api-reference/energy-accounts) - Get energy account details
* [Consents](/data-api/api-reference/consents) - View consent permissions


---

# Income (/data-api/api-reference/income)

Get income data derived from transaction analysis.



The Income endpoint provides income analysis derived from an end user's transaction history. This helps identify regular income sources and patterns.

Endpoints [#endpoints]

| Method | Endpoint     | Description                     |
| ------ | ------------ | ------------------------------- |
| `GET`  | `/v1/income` | Get income data for an end user |

The Income Model [#the-income-model]

| Attribute        | Type   | Description                                       |
| ---------------- | ------ | ------------------------------------------------- |
| `account_id`     | string | ID of the account the income was detected in      |
| `source`         | string | Identified income source (e.g., employer name)    |
| `frequency`      | string | Detected frequency (WEEKLY, FORTNIGHTLY, MONTHLY) |
| `average_amount` | number | Average income amount per period                  |
| `last_amount`    | number | Most recent income amount                         |
| `last_date`      | string | Date of most recent income                        |
| `confidence`     | number | Confidence score (0-1)                            |

Example Response [#example-response]

```json
{
  "account_id": "acc_123456789",
  "source": "ACME CORPORATION",
  "frequency": "FORTNIGHTLY",
  "average_amount": 3450.00,
  "last_amount": 3500.00,
  "last_date": "2023-01-15",
  "confidence": 0.95
}
```

Get Income Data [#get-income-data]

Retrieve income analysis for an end user.

```
GET https://api.fiskil.com/v1/income
```

Query Parameters [#query-parameters]

| Parameter     | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `end_user_id` | string | Yes      | The ID of the end user        |
| `account_id`  | string | No       | Filter by specific account ID |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/income?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/income?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const incomeData = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/income',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    income_data = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "account_id": "acc_123456789",
      "source": "ACME CORPORATION",
      "frequency": "FORTNIGHTLY",
      "average_amount": 3450.00,
      "last_amount": 3500.00,
      "last_date": "2023-01-15",
      "confidence": 0.95
    },
    {
      "account_id": "acc_123456789",
      "source": "FREELANCE CLIENT",
      "frequency": "MONTHLY",
      "average_amount": 800.00,
      "last_amount": 1000.00,
      "last_date": "2023-01-10",
      "confidence": 0.72
    }
  ]
}
```

Income Frequencies [#income-frequencies]

| Frequency     | Description                     |
| ------------- | ------------------------------- |
| `WEEKLY`      | Income received weekly          |
| `FORTNIGHTLY` | Income received every two weeks |
| `MONTHLY`     | Income received monthly         |
| `IRREGULAR`   | Irregular or variable income    |

Confidence Score [#confidence-score]

The confidence score indicates how certain the algorithm is about the detected income pattern:

| Score Range | Interpretation                               |
| ----------- | -------------------------------------------- |
| 0.9 - 1.0   | High confidence (regular, consistent income) |
| 0.7 - 0.9   | Medium confidence (mostly regular income)    |
| 0.5 - 0.7   | Low confidence (irregular or recent pattern) |
| \< 0.5      | Very low confidence (may not be reliable)    |

Use Cases [#use-cases]

* **Loan Applications**: Verify income for lending decisions
* **Affordability Checks**: Assess ability to pay for services
* **Financial Planning**: Help users understand their income patterns
* **Subscription Pricing**: Offer pricing based on income levels

Related Endpoints [#related-endpoints]

* [Transactions](/data-api/api-reference/getBankingTransactions) - View the underlying transactions
* [Accounts](/data-api/api-reference/accounts) - Get account details


---

# Introduction (/data-api/api-reference)

Welcome to the Fiskil API documentation—your toolkit for seamless integration with financial and energy data.



Welcome to the Fiskil API documentation—your toolkit for seamless integration with financial and energy data. Built on [RESTful principles](https://en.wikipedia.org/wiki/REST), our APIs offer developers a consistent, intuitive interface to access critical data from multiple sources with ease.

Why Fiskil? [#why-fiskil]

Fiskil takes the complexity out of data integration. We handle the heavy lifting of security, compliance, and data normalisation, so you can focus on building innovative applications. Whether you're working on the next fintech breakthrough, enhancing banking platforms, or optimising energy management systems, Fiskil connects you to [banks, credit unions, energy providers, and non-bank lenders](https://www.fiskil.com/product/data-provider)—all with industry-leading security and compliance.

From startups pushing the boundaries of innovation to enterprises scaling robust solutions, Fiskil's APIs are designed to grow with your business. Our [seamless onboarding process](/data-api/guides/getting-started/quick-start) gets you up and running quickly, ensuring a smooth transition from development to production.

Get Started in Minutes [#get-started-in-minutes]

Use the Base URL below to interact with the API for both testing and production environments. Environment selection is handled via your [API key and configuration settings](/data-api/api-reference/authentication)—no need to switch URLs.

<Callout type="info">
  **Base URL**

  ```
  https://api.fiskil.com/v1
  ```
</Callout>

Need a personalized walkthrough? [Get in touch for a demo](https://www.fiskil.com/contact) and discover how Fiskil can power your next project.

Our Terminology [#our-terminology]

* **Institutions**: Data holders such as banks, credit unions, energy providers, and non-bank lenders.
* **Client**: The application you're integrating with our APIs.
* **End User**: An individual or business entity connecting their data to your application.

API Overview [#api-overview]

Core Resources [#core-resources]

| Resource                                                     | Description                               |
| ------------------------------------------------------------ | ----------------------------------------- |
| [Institutions](/data-api/api-reference/institutions)         | List and retrieve data holder information |
| [Permissions](/data-api/api-reference/permissions)           | Available data permissions and scopes     |
| [Linking Accounts](/data-api/api-reference/linking-accounts) | Account linking flow management           |
| [End User](/data-api/api-reference/end-user)                 | Manage end users in your application      |
| [Consents](/data-api/api-reference/consents)                 | View and manage data sharing consents     |
| [Auth Session](/data-api/api-reference/auth-session)         | Create authorization sessions             |

Banking API [#banking-api]

| Endpoint                                                         | Description                     |
| ---------------------------------------------------------------- | ------------------------------- |
| [Accounts](/data-api/api-reference/accounts)                     | List and retrieve bank accounts |
| [Balance](/data-api/api-reference/balance)                       | Get account balances            |
| [Transactions](/data-api/api-reference/getBankingTransactions)   | Fetch transaction history       |
| [Income](/data-api/api-reference/income)                         | Get income data                 |
| [Products](/data-api/api-reference/products)                     | Bank product information        |
| [Payee](/data-api/api-reference/payee)                           | Payee details                   |
| [Direct Debits](/data-api/api-reference/direct-debits)           | Direct debit information        |
| [Scheduled Payments](/data-api/api-reference/scheduled-payments) | Scheduled payment details       |

Energy API [#energy-api]

| Endpoint                                                     | Description                       |
| ------------------------------------------------------------ | --------------------------------- |
| [Accounts](/data-api/api-reference/energy-accounts)          | List and retrieve energy accounts |
| [Balances](/data-api/api-reference/energy-balances)          | Get energy account balances       |
| [DER](/data-api/api-reference/der)                           | Distributed Energy Resources data |
| [Invoices](/data-api/api-reference/invoices)                 | Energy invoices                   |
| [Service Points](/data-api/api-reference/service-points)     | Service point information         |
| [Usage](/data-api/api-reference/usage)                       | Energy usage data                 |
| [Billing](/data-api/api-reference/billing)                   | Billing information               |
| [Concessions](/data-api/api-reference/concessions)           | Applied concessions               |
| [Plans](/data-api/api-reference/plans)                       | Energy plan details               |
| [Payment Schedule](/data-api/api-reference/payment-schedule) | Payment schedule information      |

Identity [#identity]

| Endpoint                                     | Description                                   |
| -------------------------------------------- | --------------------------------------------- |
| [Identity](/data-api/api-reference/identity) | Identity information across all account types |


---

# Institutions (/data-api/api-reference/institutions)

List and retrieve institution (data holder) information from the Fiskil API.



Institutions are commonly known as Data Holders within the Consumer Data Right. They are typically banks, credit unions, or energy providers who return information about end users. Their response contains media, names, and identifiers which can be used for displaying specific information to your end users.

The Fiskil API supports many different institutions and continues to grow and work with more.

Endpoints [#endpoints]

| Method | Endpoint                | Description                     |
| ------ | ----------------------- | ------------------------------- |
| `GET`  | `/v1/institutions`      | List all institutions           |
| `GET`  | `/v1/institutions/{id}` | Retrieve a specific institution |

The Institution Model [#the-institution-model]

| Attribute       | Type    | Required | Description                                                                                    |
| --------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
| `id`            | string  | Yes      | The ID of the institution                                                                      |
| `name`          | string  | Yes      | The name of the institution                                                                    |
| `icon`          | string  | Yes      | A URL to an icon for the institution                                                           |
| `logo`          | string  | Yes      | A URL to the logo of the institution                                                           |
| `industry`      | string  | Yes      | The industry of the institution. Values: `banking`, `energy`                                   |
| `is_accessible` | boolean | No       | Whether this institution is accessible by your team. Determines if the institution can be used |
| `priority`      | integer | Yes      | The order that this institution will appear in during an auth session                          |
| `status`        | object  | Yes      | Status information including connection status                                                 |

Example Response [#example-response]

```json
{
  "icon": "https://eastpaclogo.com.au/eastpac-icon.svg",
  "id": "22",
  "industry": "banking",
  "is_accessible": true,
  "logo": "https://eastpaclogo.com.au/eastpac.svg",
  "name": "Eastpac",
  "priority": 1,
  "status": {
    "connections": {
      "status": "DEGRADED"
    }
  }
}
```

List All Institutions [#list-all-institutions]

Returns a list of all institutions that are currently supported by Fiskil.

```
GET https://api.fiskil.com/v1/institutions
```

Query Parameters [#query-parameters]

| Parameter          | Type   | Required | Description                                                                 |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------- |
| `industry`         | string | No       | The type of the institution. Values: `banking`, `energy`                    |
| `client_id`        | string | Yes      | Your team ID. You can get this from the settings menu of the Fiskil Console |
| `institution_mode` | string | No       | If set to `recommended`, will load recommended institution data only        |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/institutions?industry=banking&client_id={client_id}' \
      --header 'accept: application/json; charset=UTF-8' \
      --header 'content-type: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/institutions?industry=banking&client_id={client_id}',
      {
        method: 'GET',
        headers: {
          'accept': 'application/json; charset=UTF-8',
          'content-type': 'application/json; charset=UTF-8'
        }
      }
    );

    const institutions = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/institutions',
        params={
            'industry': 'banking',
            'client_id': '{client_id}'
        },
        headers={
            'accept': 'application/json; charset=UTF-8',
            'content-type': 'application/json; charset=UTF-8'
        }
    )

    institutions = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
[
  {
    "icon": "https://eastpaclogo.com.au/eastpac-icon.svg",
    "id": "22",
    "industry": "banking",
    "is_accessible": true,
    "logo": "https://eastpaclogo.com.au/eastpac.svg",
    "name": "Eastpac",
    "priority": 1,
    "status": {
      "connections": {
        "status": "HEALTHY"
      }
    }
  },
  {
    "icon": "https://westbank.com.au/icon.svg",
    "id": "23",
    "industry": "banking",
    "is_accessible": true,
    "logo": "https://westbank.com.au/logo.svg",
    "name": "Westbank",
    "priority": 2,
    "status": {
      "connections": {
        "status": "HEALTHY
    }
  }
]
```

Retrieve an Institution [#retrieve-an-institution]

Retrieve a specific institution based on its ID.

```
GET https://api.fiskil.com/v1/institutions/{id}
```

Path Parameters [#path-parameters]

| Parameter | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `id`      | string | Yes      | The ID of the institution to fetch |

Example Request [#example-request-1]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url https://api.fiskil.com/v1/institutions/22 \
      --header 'accept: application/json; charset=UTF-8' \
      --header 'content-type: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/institutions/22',
      {
        method: 'GET',
        headers: {
          'accept': 'application/json; charset=UTF-8',
          'content-type': 'application/json; charset=UTF-8'
        }
      }
    );

    const institution = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/institutions/22',
        headers={
            'accept': 'application/json; charset=UTF-8',
            'content-type': 'application/json; charset=UTF-8'
        }
    )

    institution = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-2]

```json
{
  "icon": "https://eastpaclogo.com.au/eastpac-icon.svg",
  "id": "22",
  "industry": "banking",
  "is_accessible": true,
  "logo": "https://eastpaclogo.com.au/eastpac.svg",
  "name": "Eastpac",
  "priority": 1,
  "status": {
    "connections": {
      "status": "HEALTHY"
    }
  }
}
```

Status Values [#status-values]

The `status.connections.status` field can have the following values:

| Status     | Description                                          |
| ---------- | ---------------------------------------------------- |
| `HEALTHY`  | The institution is fully operational                 |
| `DEGRADED` | The institution is experiencing degraded performance |
| `OUTAGE`   | The institution is currently unavailable             |


---

# Invoices (/data-api/api-reference/invoices)

Get energy invoice data from the Fiskil API.



The Invoices endpoint provides access to energy bill/invoice data.

Endpoints [#endpoints]

| Method | Endpoint       | Description                  |
| ------ | -------------- | ---------------------------- |
| `GET`  | `/v1/invoices` | Get invoices for an end user |

The Invoice Model [#the-invoice-model]

| Attribute        | Type   | Description                            |
| ---------------- | ------ | -------------------------------------- |
| `id`             | string | Unique invoice identifier              |
| `account_id`     | string | ID of the energy account               |
| `invoice_number` | string | Invoice reference number               |
| `issue_date`     | string | Date the invoice was issued            |
| `due_date`       | string | Payment due date                       |
| `period_start`   | string | Billing period start date              |
| `period_end`     | string | Billing period end date                |
| `total_amount`   | number | Total invoice amount                   |
| `currency`       | string | Currency code                          |
| `status`         | string | Invoice status (PAID, UNPAID, OVERDUE) |

Example Response [#example-response]

```json
{
  "id": "inv_123",
  "account_id": "energy_acc_123",
  "invoice_number": "INV-2023-001234",
  "issue_date": "2023-01-01",
  "due_date": "2023-01-15",
  "period_start": "2022-12-01",
  "period_end": "2022-12-31",
  "total_amount": 185.50,
  "currency": "AUD",
  "status": "PAID"
}
```

Get Invoices [#get-invoices]

Retrieve invoice data for an end user's energy accounts.

```
GET https://api.fiskil.com/v1/invoices
```

Query Parameters [#query-parameters]

| Parameter     | Type    | Required | Description                              |
| ------------- | ------- | -------- | ---------------------------------------- |
| `end_user_id` | string  | Yes      | The ID of the end user                   |
| `account_id`  | string  | No       | Filter by specific account ID            |
| `status`      | string  | No       | Filter by status (PAID, UNPAID, OVERDUE) |
| `page[size]`  | integer | No       | Number of results (max 1000)             |
| `page[after]` | string  | No       | Cursor for pagination                    |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/invoices?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/invoices?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const invoices = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/invoices',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    invoices = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "inv_123",
      "account_id": "energy_acc_123",
      "invoice_number": "INV-2023-001234",
      "issue_date": "2023-01-01",
      "due_date": "2023-01-15",
      "period_start": "2022-12-01",
      "period_end": "2022-12-31",
      "total_amount": 185.50,
      "currency": "AUD",
      "status": "PAID"
    },
    {
      "id": "inv_124",
      "account_id": "energy_acc_123",
      "invoice_number": "INV-2023-001235",
      "issue_date": "2023-02-01",
      "due_date": "2023-02-15",
      "period_start": "2023-01-01",
      "period_end": "2023-01-31",
      "total_amount": 198.75,
      "currency": "AUD",
      "status": "UNPAID"
    }
  ]
}
```

Invoice Statuses [#invoice-statuses]

| Status    | Description                 |
| --------- | --------------------------- |
| `PAID`    | Invoice has been fully paid |
| `UNPAID`  | Invoice is pending payment  |
| `OVERDUE` | Invoice is past due date    |
| `PARTIAL` | Invoice is partially paid   |

Related Endpoints [#related-endpoints]

* [Billing](/data-api/api-reference/billing) - Get billing transactions
* [Energy Balances](/data-api/api-reference/energy-balances) - Get current balance


---

# Linking Accounts (/data-api/api-reference/linking-accounts)

Understanding the account linking flow in the Fiskil API.



Linking accounts is the process of connecting an end user's financial or energy accounts to your application. This enables you to access their data with their explicit consent.

The Account Linking Flow [#the-account-linking-flow]

The account linking process follows these steps:

<Steps>
  <Step>
    Create an End User [#create-an-end-user]

    First, [create an end user](/data-api/api-reference/end-user#add-end-user) in the Fiskil platform to represent your user.

    ```bash
    curl --request POST \
      --url https://api.fiskil.com/v1/end-users \
      --header 'Authorization: Bearer {access_token}' \
      --header 'content-type: application/json' \
      --data '{
        "email": "user@example.com",
        "name": "John Doe"
      }'
    ```
  </Step>

  <Step>
    Start an Auth Session [#start-an-auth-session]

    [Create an auth session](/data-api/api-reference/auth-session) for the end user. This generates a session ID that is used with the Link SDK to launch the consent flow.

    ```bash
    curl --request POST \
      --url https://api.fiskil.com/v1/auth/session \
      --header 'Authorization: Bearer {access_token}' \
      --header 'content-type: application/json' \
      --data '{
        "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5"
      }'
    ```

    <Callout type="info">
      When using the Link SDK, you don't need to provide `redirect_uri` or `cancel_uri` — the SDK handles the flow result directly via a promise.
    </Callout>
  </Step>

  <Step>
    Launch the Link SDK [#launch-the-link-sdk]

    In your frontend, pass the `auth_session_id` from the response to the Link SDK's `link()` function. This opens the consent UI embedded in your application. The user will:

    1. Select their institution (bank or energy provider)
    2. Log in to their institution
    3. Select which accounts to share
    4. Confirm the consent

    ```javascript
    import { link } from '@fiskil/link';

    const flow = link(authSession.session_id);
    ```
  </Step>

  <Step>
    Handle the Result [#handle-the-result]

    When the consent flow completes, the SDK resolves with a `consentID` you can use to fetch data. If the user cancels or an error occurs, the promise rejects with a typed error.

    ```javascript
    try {
      const result = await flow;
      console.log('Consent ID:', result.consentID);
      // Use consentID to fetch data via Fiskil APIs
    } catch (err) {
      console.error('Link error:', err.code);
    }
    ```
  </Step>

  <Step>
    Access Data [#access-data]

    Once the consent is established, use the `consentID` to start accessing the user's data through the [Banking](/data-api/api-reference/accounts) and [Energy](/data-api/api-reference/energy-accounts) API endpoints.
  </Step>
</Steps>

Integrating the Link SDK [#integrating-the-link-sdk]

The [Fiskil Link SDK](https://github.com/Fiskil/link) supports both ESM/TypeScript and UMD/CDN usage, with options for timeout configuration, origin restrictions, and programmatic cancellation. For install instructions, full code examples, error codes, and a React integration example, see the [Integrating the Link SDK](/data-api/guides/link-widget/integrating-the-link-sdk) guide.

Customizing the Flow [#customizing-the-flow]

You can customize the consent flow experience through the [Fiskil Console](https://console.fiskil.com/data-api/customize-ui):

* **Branding**: Add your logo and colors
* **Institution Selection**: Control which institutions are displayed
* **Copy**: Customize the text shown to users

Handling Multiple Consents [#handling-multiple-consents]

An end user can have multiple active consents:

* Multiple consents to different institutions
* Multiple consents to the same institution (e.g., different accounts)

Use the [Consents API](/data-api/api-reference/consents) to manage and track all consents for an end user.

Best Practices [#best-practices]

1. **Handle Errors with Error Codes**: The Link SDK rejects with typed `LinkError` objects containing specific error codes (e.g., `LINK_USER_CANCELLED`, `CONSENT_ENDUSER_DENIED`). Use these codes to provide meaningful feedback to your users. See [Errors](/data-api/api-reference/errors) for a complete list.

2. **Pre-select the Institution**: If you know which institution the user wants to connect, pass the `institution_id` in the auth session request to skip the institution selection step.

3. **Monitor Consent Status**: Consents can expire or be revoked. Use [webhooks](/data-api/guides/core-concepts/webhooks) to stay informed about consent status changes.

4. **Explain the Value**: Before starting the consent flow, explain to users what data you need and why, to improve conversion rates.


---

# Pagination (/data-api/api-reference/pagination)

How to handle paginated responses from the Fiskil API.



All top-level API endpoints that fetch resources in bulk (list APIs) support cursor-based pagination, such as list banking accounts, energy accounts list, list transactions, list all bills, and more.

The API includes URL links to fetch previous and next sets of items, so for simple pagination needs, clients can simply use the links provided in the response.

How It Works [#how-it-works]

Cursor pagination, also known as keyset pagination, uses a specific pointer (the cursor) from the previous result set to fetch the next set of items. This method avoids the performance issues associated with skipping a large number of rows.

Query Parameters [#query-parameters]

| Parameter      | Type    | Required | Description                                                                                       |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------- |
| `page[before]` | string  | No       | A pointer to a specific item in the dataset. The API returns results before this item.            |
| `page[after]`  | string  | No       | A pointer to a specific item in the dataset. The API returns results after this item.             |
| `page[size]`   | integer | No       | The number of resources that will be included in the response's data field. It is capped at 1000. |

Response Fields [#response-fields]

The response will contain additional `links` fields:

| Field  | Description                        |
| ------ | ---------------------------------- |
| `prev` | A URI to request the previous page |
| `next` | A URI to request the next page     |

Usage [#usage]

The initial request does not require a cursor. The response will include links to fetch the previous or next set of items (if they exist).

**Example:**

1. Initial request: `GET /api/items`
2. Following request: `GET /api/items?page[after]=abc123`

Example Response [#example-response]

```json
{
  "data": [
    {
      "id": "acc_123",
      "name": "Main Account"
    },
    {
      "id": "acc_456",
      "name": "Savings Account"
    }
  ],
  "links": {
    "prev": "https://api.fiskil.com/v1/items?page[before]=abc123",
    "next": "https://api.fiskil.com/v1/items?page[after]=xyz789"
  }
}
```

Best Practices [#best-practices]

1. **Use links when available**: The response links (`prev`, `next`) are pre-computed and guaranteed to work correctly.

2. **Handle empty pages**: When you receive an empty data array or no `next` link, you've reached the end of the results.

3. **Respect rate limits**: Avoid making rapid sequential pagination requests. Add reasonable delays between requests.

4. **Cache when appropriate**: If your data doesn't change frequently, consider caching paginated results to reduce API calls.


---

# Payee (/data-api/api-reference/payee)

Get payee information from the Fiskil API.



The Payee endpoint provides information about saved payees on an end user's accounts.

Endpoints [#endpoints]

| Method | Endpoint     | Description                |
| ------ | ------------ | -------------------------- |
| `GET`  | `/v1/payees` | Get payees for an end user |

The Payee Model [#the-payee-model]

| Attribute        | Type   | Description                                     |
| ---------------- | ------ | ----------------------------------------------- |
| `id`             | string | Unique identifier for the payee                 |
| `nickname`       | string | Nickname or description for the payee           |
| `type`           | string | Type of payee (DOMESTIC, BILLER, INTERNATIONAL) |
| `account_number` | string | Payee's account number (may be masked)          |
| `bsb`            | string | Payee's BSB (for domestic payees)               |
| `biller_code`    | string | Biller code (for BPAY payees)                   |
| `created_date`   | string | When the payee was created                      |

Example Response [#example-response]

```json
{
  "id": "payee_123",
  "nickname": "Rent - ABC Property",
  "type": "DOMESTIC",
  "account_number": "****5678",
  "bsb": "123-456",
  "biller_code": null,
  "created_date": "2022-06-15"
}
```

Get Payees [#get-payees]

Retrieve payee information for an end user.

```
GET https://api.fiskil.com/v1/payees
```

Query Parameters [#query-parameters]

| Parameter     | Type   | Required | Description                                            |
| ------------- | ------ | -------- | ------------------------------------------------------ |
| `end_user_id` | string | Yes      | The ID of the end user                                 |
| `type`        | string | No       | Filter by payee type (DOMESTIC, BILLER, INTERNATIONAL) |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/payees?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/payees?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const payees = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/payees',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    payees = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "payee_123",
      "nickname": "Rent - ABC Property",
      "type": "DOMESTIC",
      "account_number": "****5678",
      "bsb": "123-456",
      "biller_code": null,
      "created_date": "2022-06-15"
    },
    {
      "id": "payee_456",
      "nickname": "Electricity",
      "type": "BILLER",
      "account_number": null,
      "bsb": null,
      "biller_code": "12345",
      "created_date": "2022-08-20"
    }
  ]
}
```

Payee Types [#payee-types]

| Type            | Description                   |
| --------------- | ----------------------------- |
| `DOMESTIC`      | Australian bank account payee |
| `BILLER`        | BPAY biller                   |
| `INTERNATIONAL` | International transfer payee  |

Related Endpoints [#related-endpoints]

* [Accounts](/data-api/api-reference/accounts) - Get account details
* [Scheduled Payments](/data-api/api-reference/scheduled-payments) - Get scheduled payments


---

# Payment Schedule (/data-api/api-reference/payment-schedule)

Get payment schedule information for energy accounts from the Fiskil API.



The Payment Schedule endpoint provides information about payment arrangements and scheduled payments for energy accounts.

Endpoints [#endpoints]

| Method | Endpoint               | Description                           |
| ------ | ---------------------- | ------------------------------------- |
| `GET`  | `/v1/payment-schedule` | Get payment schedules for an end user |

The Payment Schedule Model [#the-payment-schedule-model]

| Attribute           | Type   | Description                                           |
| ------------------- | ------ | ----------------------------------------------------- |
| `id`                | string | Unique schedule identifier                            |
| `account_id`        | string | Associated energy account ID                          |
| `type`              | string | Payment type (DIRECT\_DEBIT, BILL\_SMOOTHING, MANUAL) |
| `frequency`         | string | Payment frequency                                     |
| `amount`            | number | Payment amount (for fixed payments)                   |
| `next_payment_date` | string | Next scheduled payment date                           |
| `payment_method`    | string | Payment method                                        |

Example Response [#example-response]

```json
{
  "id": "ps_123",
  "account_id": "energy_acc_123",
  "type": "DIRECT_DEBIT",
  "frequency": "MONTHLY",
  "amount": null,
  "next_payment_date": "2023-02-15",
  "payment_method": "BANK_ACCOUNT"
}
```

Get Payment Schedules [#get-payment-schedules]

Retrieve payment schedule information for an end user's energy accounts.

```
GET https://api.fiskil.com/v1/payment-schedule
```

Query Parameters [#query-parameters]

| Parameter     | Type    | Required | Description                   |
| ------------- | ------- | -------- | ----------------------------- |
| `end_user_id` | string  | Yes      | The ID of the end user        |
| `account_id`  | string  | No       | Filter by specific account ID |
| `page[size]`  | integer | No       | Number of results (max 1000)  |
| `page[after]` | string  | No       | Cursor for pagination         |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/payment-schedule?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/payment-schedule?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const schedules = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/payment-schedule',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    schedules = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "ps_123",
      "account_id": "energy_acc_123",
      "type": "DIRECT_DEBIT",
      "frequency": "MONTHLY",
      "amount": null,
      "next_payment_date": "2023-02-15",
      "payment_method": "BANK_ACCOUNT"
    },
    {
      "id": "ps_456",
      "account_id": "energy_acc_456",
      "type": "BILL_SMOOTHING",
      "frequency": "FORTNIGHTLY",
      "amount": 85.00,
      "next_payment_date": "2023-01-27",
      "payment_method": "CREDIT_CARD"
    }
  ]
}
```

Payment Types [#payment-types]

| Type             | Description                                 |
| ---------------- | ------------------------------------------- |
| `DIRECT_DEBIT`   | Automatic payment of bill amount            |
| `BILL_SMOOTHING` | Fixed regular payments to smooth bills      |
| `MANUAL`         | Customer pays manually when bill issued     |
| `PAYMENT_PLAN`   | Structured payment plan (e.g., for arrears) |

Payment Methods [#payment-methods]

| Method         | Description                    |
| -------------- | ------------------------------ |
| `BANK_ACCOUNT` | Direct debit from bank account |
| `CREDIT_CARD`  | Credit card payment            |
| `BPAY`         | BPAY payment                   |

Related Endpoints [#related-endpoints]

* [Energy Accounts](/data-api/api-reference/energy-accounts) - Get account details
* [Billing](/data-api/api-reference/billing) - Get billing history
* [Invoices](/data-api/api-reference/invoices) - Get invoice details


---

# Permissions (/data-api/api-reference/permissions)

Understanding data permissions and scopes in the Fiskil API.



Permissions define what data your application can access from an end user's accounts. When an end user authorizes your application, they grant specific permissions that determine which API endpoints you can call.

Permission Scopes [#permission-scopes]

Fiskil organizes permissions into logical groups based on the type of data they provide access to.

Banking Permissions [#banking-permissions]

| Permission           | Description                             | Related Endpoints                                                |
| -------------------- | --------------------------------------- | ---------------------------------------------------------------- |
| `accounts`           | Access to account details               | [Accounts](/data-api/api-reference/accounts)                     |
| `balances`           | Access to account balances              | [Balance](/data-api/api-reference/balance)                       |
| `transactions`       | Access to transaction history           | [Transactions](/data-api/api-reference/getBankingTransactions)   |
| `payees`             | Access to payee information             | [Payee](/data-api/api-reference/payee)                           |
| `direct_debits`      | Access to direct debit information      | [Direct Debits](/data-api/api-reference/direct-debits)           |
| `scheduled_payments` | Access to scheduled payment information | [Scheduled Payments](/data-api/api-reference/scheduled-payments) |

Energy Permissions [#energy-permissions]

| Permission         | Description                                 | Related Endpoints                                            |
| ------------------ | ------------------------------------------- | ------------------------------------------------------------ |
| `energy_accounts`  | Access to energy account details            | [Energy Accounts](/data-api/api-reference/energy-accounts)   |
| `energy_balances`  | Access to energy account balances           | [Energy Balances](/data-api/api-reference/energy-balances)   |
| `usage`            | Access to energy usage data                 | [Usage](/data-api/api-reference/usage)                       |
| `billing`          | Access to billing information               | [Billing](/data-api/api-reference/billing)                   |
| `invoices`         | Access to invoice data                      | [Invoices](/data-api/api-reference/invoices)                 |
| `concessions`      | Access to concession information            | [Concessions](/data-api/api-reference/concessions)           |
| `service_points`   | Access to service point information         | [Service Points](/data-api/api-reference/service-points)     |
| `der`              | Access to Distributed Energy Resources data | [DER](/data-api/api-reference/der)                           |
| `payment_schedule` | Access to payment schedule information      | [Payment Schedule](/data-api/api-reference/payment-schedule) |

Common Permissions [#common-permissions]

| Permission | Description                    | Related Endpoints                            |
| ---------- | ------------------------------ | -------------------------------------------- |
| `identity` | Access to identity information | [Identity](/data-api/api-reference/identity) |

Requesting Permissions [#requesting-permissions]

Permissions are requested during the [auth session](/data-api/api-reference/auth-session) creation. The end user will see which permissions your application is requesting and can choose to grant or deny access.

Example: Requesting Permissions [#example-requesting-permissions]

When creating an auth session, you can specify which permissions to request:

```json
{
  "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
  "permissions": ["accounts", "balances", "transactions"],
  "redirect_uri": "https://yourapp.com/callback"
}
```

Checking Granted Permissions [#checking-granted-permissions]

You can check which permissions have been granted for a specific consent by using the [Consents API](/data-api/api-reference/consents). The `permissions` field in the consent response will list all granted permissions.

Example Consent Response [#example-consent-response]

```json
{
  "arrangement_id": "94549a73-a554-4b76-b824-d96898829751",
  "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
  "permissions": [
    "accounts",
    "balances",
    "transactions"
  ],
  "active": true,
  "expires_at": "2023-01-01T10:42:40Z"
}
```

Best Practices [#best-practices]

1. **Request Only What You Need**: Only request permissions for data you actually need. This improves user trust and conversion rates.

2. **Explain Why You Need Each Permission**: In your UI, explain to users why you need each permission before they start the consent flow.

3. **Handle Missing Permissions Gracefully**: If an API call fails due to missing permissions, provide clear guidance to users on how to grant additional permissions.

4. **Monitor Permission Usage**: Track which permissions you're actively using and consider removing unused ones from your requests.


---

# Plans (/data-api/api-reference/plans)

Get energy plan information from the Fiskil API.



The Plans endpoint provides information about energy plans and tariffs associated with an end user's accounts.

Endpoints [#endpoints]

| Method | Endpoint    | Description                      |
| ------ | ----------- | -------------------------------- |
| `GET`  | `/v1/plans` | Get plan details for an end user |

The Plan Model [#the-plan-model]

| Attribute        | Type   | Description                              |
| ---------------- | ------ | ---------------------------------------- |
| `id`             | string | Unique plan identifier                   |
| `account_id`     | string | Associated energy account ID             |
| `name`           | string | Plan name                                |
| `description`    | string | Plan description                         |
| `fuel_type`      | string | Fuel type (ELECTRICITY, GAS, DUAL\_FUEL) |
| `tariff_type`    | string | Tariff structure type                    |
| `effective_from` | string | When the plan became effective           |
| `effective_to`   | string | When the plan ends (if applicable)       |
| `rates`          | array  | Rate/tariff information                  |

Example Response [#example-response]

```json
{
  "id": "plan_123",
  "account_id": "energy_acc_123",
  "name": "Residential Saver",
  "description": "Competitive rates for residential customers",
  "fuel_type": "ELECTRICITY",
  "tariff_type": "TIME_OF_USE",
  "effective_from": "2023-01-01",
  "effective_to": null,
  "rates": [
    {
      "rate_type": "PEAK",
      "unit_price": 0.35,
      "unit": "kWh",
      "time_of_use": {
        "start": "14:00",
        "end": "20:00",
        "days": ["WEEKDAY"]
      }
    },
    {
      "rate_type": "OFF_PEAK",
      "unit_price": 0.18,
      "unit": "kWh",
      "time_of_use": {
        "start": "20:00",
        "end": "14:00",
        "days": ["WEEKDAY", "WEEKEND"]
      }
    }
  ]
}
```

Get Plans [#get-plans]

Retrieve plan information for an end user's energy accounts.

```
GET https://api.fiskil.com/v1/plans
```

Query Parameters [#query-parameters]

| Parameter     | Type    | Required | Description                   |
| ------------- | ------- | -------- | ----------------------------- |
| `end_user_id` | string  | Yes      | The ID of the end user        |
| `account_id`  | string  | No       | Filter by specific account ID |
| `page[size]`  | integer | No       | Number of results (max 1000)  |
| `page[after]` | string  | No       | Cursor for pagination         |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/plans?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/plans?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const plans = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/plans',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    plans = response.json()
    ```
  </Tab>
</Tabs>

Tariff Types [#tariff-types]

| Type          | Description                          |
| ------------- | ------------------------------------ |
| `FLAT`        | Single rate for all usage            |
| `TIME_OF_USE` | Different rates based on time of day |
| `TIERED`      | Rates change based on usage tiers    |
| `DEMAND`      | Includes demand charges              |

Rate Types [#rate-types]

| Type              | Description                       |
| ----------------- | --------------------------------- |
| `PEAK`            | Peak period rate                  |
| `OFF_PEAK`        | Off-peak period rate              |
| `SHOULDER`        | Shoulder period rate              |
| `CONTROLLED_LOAD` | Controlled load (hot water, etc.) |
| `FEED_IN`         | Solar feed-in tariff              |

Related Endpoints [#related-endpoints]

* [Energy Accounts](/data-api/api-reference/energy-accounts) - Get account details
* [Usage](/data-api/api-reference/usage) - Get usage to calculate costs


---

# Products (/data-api/api-reference/products)

Get bank product information from the Fiskil API.



The Products endpoint provides detailed information about banking products associated with an end user's accounts.

Endpoints [#endpoints]

| Method | Endpoint       | Description                                    |
| ------ | -------------- | ---------------------------------------------- |
| `GET`  | `/v1/products` | Get product details for an end user's accounts |

The Product Model [#the-product-model]

| Attribute        | Type   | Description                       |
| ---------------- | ------ | --------------------------------- |
| `id`             | string | Unique identifier for the product |
| `account_id`     | string | ID of the associated account      |
| `name`           | string | Product name                      |
| `description`    | string | Product description               |
| `category`       | string | Product category                  |
| `features`       | array  | List of product features          |
| `fees`           | array  | Associated fees                   |
| `interest_rates` | array  | Interest rate information         |

Example Response [#example-response]

```json
{
  "id": "prod_123",
  "account_id": "acc_123456789",
  "name": "Complete Freedom Account",
  "description": "Everyday transaction account with no monthly fees",
  "category": "TRANS_AND_SAVINGS_ACCOUNTS",
  "features": [
    "No monthly account keeping fees",
    "Unlimited transactions",
    "Free ATM withdrawals"
  ],
  "fees": [
    {
      "name": "International transaction fee",
      "amount": 3.00,
      "currency": "AUD"
    }
  ],
  "interest_rates": [
    {
      "rate": 0.01,
      "type": "VARIABLE",
      "description": "Base interest rate"
    }
  ]
}
```

Get Products [#get-products]

Retrieve product information for an end user's accounts.

```
GET https://api.fiskil.com/v1/products
```

Query Parameters [#query-parameters]

| Parameter     | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `end_user_id` | string | Yes      | The ID of the end user        |
| `account_id`  | string | No       | Filter by specific account ID |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/products?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/products?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const products = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/products',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    products = response.json()
    ```
  </Tab>
</Tabs>

Related Endpoints [#related-endpoints]

* [Accounts](/data-api/api-reference/accounts) - Get account details


---

# Scheduled Payments (/data-api/api-reference/scheduled-payments)

Get scheduled payment information from the Fiskil API.



The Scheduled Payments endpoint provides information about future scheduled payments on an end user's accounts.

Endpoints [#endpoints]

| Method | Endpoint                 | Description                            |
| ------ | ------------------------ | -------------------------------------- |
| `GET`  | `/v1/scheduled-payments` | Get scheduled payments for an end user |

The Scheduled Payment Model [#the-scheduled-payment-model]

| Attribute           | Type   | Description                                 |
| ------------------- | ------ | ------------------------------------------- |
| `id`                | string | Unique identifier for the scheduled payment |
| `account_id`        | string | ID of the source account                    |
| `payee_reference`   | string | Reference or description for the payment    |
| `amount`            | number | Payment amount                              |
| `currency`          | string | Currency code                               |
| `frequency`         | string | Payment frequency                           |
| `next_payment_date` | string | Date of the next scheduled payment          |
| `status`            | string | Status of the scheduled payment             |

Example Response [#example-response]

```json
{
  "id": "sp_123",
  "account_id": "acc_123456789",
  "payee_reference": "Rent Payment",
  "amount": 1500.00,
  "currency": "AUD",
  "frequency": "MONTHLY",
  "next_payment_date": "2023-02-01",
  "status": "ACTIVE"
}
```

Get Scheduled Payments [#get-scheduled-payments]

Retrieve scheduled payment information for an end user.

```
GET https://api.fiskil.com/v1/scheduled-payments
```

Query Parameters [#query-parameters]

| Parameter     | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `end_user_id` | string | Yes      | The ID of the end user        |
| `account_id`  | string | No       | Filter by specific account ID |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/scheduled-payments?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/scheduled-payments?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const scheduledPayments = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/scheduled-payments',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    scheduled_payments = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "sp_123",
      "account_id": "acc_123456789",
      "payee_reference": "Rent Payment",
      "amount": 1500.00,
      "currency": "AUD",
      "frequency": "MONTHLY",
      "next_payment_date": "2023-02-01",
      "status": "ACTIVE"
    },
    {
      "id": "sp_456",
      "account_id": "acc_123456789",
      "payee_reference": "Car Loan",
      "amount": 450.00,
      "currency": "AUD",
      "frequency": "FORTNIGHTLY",
      "next_payment_date": "2023-01-20",
      "status": "ACTIVE"
    }
  ]
}
```

Payment Frequencies [#payment-frequencies]

| Frequency     | Description              |
| ------------- | ------------------------ |
| `WEEKLY`      | Every week               |
| `FORTNIGHTLY` | Every two weeks          |
| `MONTHLY`     | Every month              |
| `QUARTERLY`   | Every three months       |
| `ANNUALLY`    | Every year               |
| `ONE_OFF`     | Single scheduled payment |

Related Endpoints [#related-endpoints]

* [Accounts](/data-api/api-reference/accounts) - Get account details
* [Direct Debits](/data-api/api-reference/direct-debits) - Get direct debit arrangements
* [Payee](/data-api/api-reference/payee) - Get payee information


---

# Service Points (/data-api/api-reference/service-points)

Get service point (NMI) information from the Fiskil API.



The Service Points endpoint provides information about National Metering Identifiers (NMIs) and meter details for energy accounts.

Endpoints [#endpoints]

| Method | Endpoint             | Description                        |
| ------ | -------------------- | ---------------------------------- |
| `GET`  | `/v1/service-points` | Get service points for an end user |

The Service Point Model [#the-service-point-model]

| Attribute        | Type   | Description                           |
| ---------------- | ------ | ------------------------------------- |
| `id`             | string | Service point identifier (NMI)        |
| `account_id`     | string | Associated energy account ID          |
| `address`        | object | Address details for the service point |
| `classification` | string | Classification (SMALL, LARGE)         |
| `status`         | string | Connection status (ACTIVE, INACTIVE)  |
| `meter_type`     | string | Type of meter installed               |
| `registers`      | array  | Meter register information            |

Example Response [#example-response]

```json
{
  "id": "NMI123456789",
  "account_id": "energy_acc_123",
  "address": {
    "street": "123 Example Street",
    "suburb": "Sydney",
    "state": "NSW",
    "postcode": "2000"
  },
  "classification": "SMALL",
  "status": "ACTIVE",
  "meter_type": "SMART",
  "registers": [
    {
      "register_id": "E1",
      "register_type": "CONSUMPTION",
      "unit": "kWh"
    }
  ]
}
```

Get Service Points [#get-service-points]

Retrieve service point information for an end user's energy accounts.

```
GET https://api.fiskil.com/v1/service-points
```

Query Parameters [#query-parameters]

| Parameter     | Type    | Required | Description                   |
| ------------- | ------- | -------- | ----------------------------- |
| `end_user_id` | string  | Yes      | The ID of the end user        |
| `account_id`  | string  | No       | Filter by specific account ID |
| `page[size]`  | integer | No       | Number of results (max 1000)  |
| `page[after]` | string  | No       | Cursor for pagination         |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/service-points?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/service-points?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const servicePoints = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/service-points',
        params={'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5'},
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    service_points = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "id": "NMI123456789",
      "account_id": "energy_acc_123",
      "address": {
        "street": "123 Example Street",
        "suburb": "Sydney",
        "state": "NSW",
        "postcode": "2000"
      },
      "classification": "SMALL",
      "status": "ACTIVE",
      "meter_type": "SMART",
      "registers": [
        {
          "register_id": "E1",
          "register_type": "CONSUMPTION",
          "unit": "kWh"
        }
      ]
    }
  ]
}
```

Meter Types [#meter-types]

| Type       | Description                    |
| ---------- | ------------------------------ |
| `SMART`    | Smart meter with interval data |
| `BASIC`    | Basic accumulation meter       |
| `INTERVAL` | Interval meter (pre-smart)     |

Register Types [#register-types]

| Type          | Description                      |
| ------------- | -------------------------------- |
| `CONSUMPTION` | Energy consumption register      |
| `GENERATION`  | Solar/generation export register |
| `DEMAND`      | Demand measurement register      |

Related Endpoints [#related-endpoints]

* [Usage](/data-api/api-reference/usage) - Get usage data for service points
* [DER](/data-api/api-reference/der) - Get DER (solar/battery) data


---

# Usage (/data-api/api-reference/usage)

Get energy usage data from the Fiskil API.



The Usage endpoint provides detailed energy consumption data, including interval data where available.

Endpoints [#endpoints]

| Method | Endpoint    | Description                    |
| ------ | ----------- | ------------------------------ |
| `GET`  | `/v1/usage` | Get usage data for an end user |

The Usage Model [#the-usage-model]

| Attribute          | Type   | Description                     |
| ------------------ | ------ | ------------------------------- |
| `service_point_id` | string | NMI or service point identifier |
| `register_id`      | string | Meter register identifier       |
| `interval_start`   | string | Start of the interval period    |
| `interval_end`     | string | End of the interval period      |
| `value`            | number | Usage value                     |
| `unit`             | string | Unit of measurement (kWh)       |
| `quality`          | string | Data quality indicator          |

Example Response [#example-response]

```json
{
  "service_point_id": "NMI123456789",
  "register_id": "E1",
  "interval_start": "2023-01-15T00:00:00+11:00",
  "interval_end": "2023-01-15T00:30:00+11:00",
  "value": 0.45,
  "unit": "kWh",
  "quality": "ACTUAL"
}
```

Get Usage Data [#get-usage-data]

Retrieve energy usage data for an end user.

```
GET https://api.fiskil.com/v1/usage
```

Query Parameters [#query-parameters]

| Parameter          | Type    | Required | Description                            |
| ------------------ | ------- | -------- | -------------------------------------- |
| `end_user_id`      | string  | Yes      | The ID of the end user                 |
| `service_point_id` | string  | No       | Filter by service point (NMI)          |
| `from_date`        | string  | No       | Start date (YYYY-MM-DD)                |
| `to_date`          | string  | No       | End date (YYYY-MM-DD)                  |
| `interval_type`    | string  | No       | Interval granularity (INTERVAL, DAILY) |
| `page[size]`       | integer | No       | Number of results (max 1000)           |
| `page[after]`      | string  | No       | Cursor for pagination                  |

Example Request [#example-request]

<Tabs items={['cURL', 'Node.js', 'Python']}>
  <Tab value="cURL">
    ```bash
    curl --request GET \
      --url 'https://api.fiskil.com/v1/usage?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5&from_date=2023-01-01&to_date=2023-01-31' \
      --header 'Authorization: Bearer {access_token}' \
      --header 'accept: application/json; charset=UTF-8'
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    const response = await fetch(
      'https://api.fiskil.com/v1/usage?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5&from_date=2023-01-01&to_date=2023-01-31',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer {access_token}',
          'accept': 'application/json; charset=UTF-8'
        }
      }
    );

    const usage = await response.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        'https://api.fiskil.com/v1/usage',
        params={
            'end_user_id': '482c0e2b-5866-46b1-b795-220b7bba45b5',
            'from_date': '2023-01-01',
            'to_date': '2023-01-31'
        },
        headers={
            'Authorization': 'Bearer {access_token}',
            'accept': 'application/json; charset=UTF-8'
        }
    )

    usage = response.json()
    ```
  </Tab>
</Tabs>

Example Response [#example-response-1]

```json
{
  "data": [
    {
      "service_point_id": "NMI123456789",
      "register_id": "E1",
      "interval_start": "2023-01-15T00:00:00+11:00",
      "interval_end": "2023-01-15T00:30:00+11:00",
      "value": 0.45,
      "unit": "kWh",
      "quality": "ACTUAL"
    },
    {
      "service_point_id": "NMI123456789",
      "register_id": "E1",
      "interval_start": "2023-01-15T00:30:00+11:00",
      "interval_end": "2023-01-15T01:00:00+11:00",
      "value": 0.38,
      "unit": "kWh",
      "quality": "ACTUAL"
    }
  ],
  "links": {
    "next": "https://api.fiskil.com/v1/usage?end_user_id=482c0e2b-5866-46b1-b795-220b7bba45b5&page[after]=xyz789"
  }
}
```

Data Quality Indicators [#data-quality-indicators]

| Quality       | Description                                |
| ------------- | ------------------------------------------ |
| `ACTUAL`      | Actual meter reading                       |
| `ESTIMATED`   | Estimated reading (meter couldn't be read) |
| `SUBSTITUTED` | Substituted value (data correction)        |

Interval Types [#interval-types]

* **INTERVAL**: 15 or 30-minute interval data (where smart meters are installed)
* **DAILY**: Daily aggregated usage

Use Cases [#use-cases]

* **Energy Monitoring**: Track consumption patterns
* **Bill Prediction**: Estimate future bills based on usage
* **Solar Analysis**: Understand generation vs consumption
* **Peak Usage Detection**: Identify high-usage periods

Related Endpoints [#related-endpoints]

* [Service Points](/data-api/api-reference/service-points) - Get NMI details
* [Billing](/data-api/api-reference/billing) - Get billing information
* [DER](/data-api/api-reference/der) - Get solar/battery data


---

# Changelog (/data-holder/changelog)

All the changes made to the documentations are listed here starting from 10-08-2023.



All the changes made to the documentations are listed here starting from 10-08-2023.

<ChangelogLayout>
  07-03-2025 (v1.5.0) [#07-03-2025-v150]

  * Adds `"open-status"` filter to Energy `Fetch Accounts for Customer` API. This parameter is required to support the CDR `Get All Accounts` API which has a filter on account open-status. Valid values are `"ALL"`, `"OPEN"`, or `"CLOSED"`. Only requested accounts with the matching open state should be returned.

  06-08-2024 (v1.4.0) [#06-08-2024-v140]

  * Updates customer search response "phoneNumber" field description to support SMS delivery of authentication OTP
  * Removes unnecessary fields "givenName", "familyName", "updatedAt", "address", "emailVerified", "email", and "phoneNumberVerified" from customer search response

  06-08-2024 (v1.3.3) [#06-08-2024-v133]

  * Clarification of banking Scheduled Payments **PaymentSet.To** properties. Full payee and account details should be returned with **accountID** and **payeeID** fields.
  * "Energy" tag added to energy industry endpoints.

  05-08-2024 (v1.3.2) [#05-08-2024-v132]

  * Adds `"is-owned"` & `"open-status"` parameters to `Obtain balances for a specified list of accounts` (POST `/v1/banking/customer/{customerId}/accounts/balances`) request
  * Adds `"is-owned"` & `"open-status"` parameters to `Obtain direct debit authorisations for a specified list of accounts` (POST `/v1/banking/customer/{customerId}/accounts/direct-debits`) request
  * Adds `"is-owned"` & `"open-status"` parameters to `Obtain scheduled payments for a specified list of accounts` (POST `/v1/banking/customer/{customerId}/payments/scheduled`) request

  05-08-2024 (v1.3.1) [#05-08-2024-v131]

  * Adds "users" property to BankingAccountDetailV3 response object in API spec

  Version 1.0.0 [#version-100]

  Added [#added]

  * Initial release of Data Holder
  * Support for custom schemas
  * Multiple specification support (CDR, FDX, PSD2)
</ChangelogLayout>


---

# Authentication (/data-holder/platform-api/authentication)

Authenticate to the Platform API using client credentials to manage products programmatically.



The Platform API uses OAuth 2.0 client credentials for authentication. This guide walks you through obtaining and using access tokens.

Prerequisites [#prerequisites]

You must have access to Product Portal in the [Fiskil Console](https://console.fiskil.com/) to generate API keys.

Generate API credentials [#generate-api-credentials]

1. Navigate to API Keys [#1-navigate-to-api-keys]

In the Fiskil Console, navigate to **API Keys** in the sidebar.

2. Select permissions [#2-select-permissions]

Generate credentials with the appropriate product management scopes:

| Scope                         | Description                                           |
| ----------------------------- | ----------------------------------------------------- |
| `api:provider.products.read`  | List and view products through internal API endpoints |
| `api:provider.products.write` | Create, update, and delete products                   |

> Public API endpoints are visible globally and do not require read permissions.

3. Store credentials securely [#3-store-credentials-securely]

After generating, the Console displays a **Client ID** and **Client Secret** pair. Store these securely - you'll need them to obtain access tokens.

<Callout type="warn">
  The client secret is only shown once. Store it in a secure location such as a secrets manager.
</Callout>

Obtain an access token [#obtain-an-access-token]

Exchange your client credentials for a short-lived access token:

```bash title="cURL"
curl -X POST https://api.fiskil.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'
```

```javascript title="Node.js"
const response = await fetch('https://api.fiskil.com/v1/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: process.env.FISKIL_CLIENT_ID,
    client_secret: process.env.FISKIL_CLIENT_SECRET
  })
});

const { token, expires_in } = await response.json();
```

```python title="Python"
import requests

response = requests.post(
    'https://api.fiskil.com/v1/token',
    json={
        'client_id': 'your_client_id',
        'client_secret': 'your_client_secret'
    }
)

data = response.json()
token = data['token']
expires_in = data['expires_in']
```

Response [#response]

```json
{
  "token": "eyJhbGc....",
  "expires_in": 900
}
```

| Field        | Type    | Description                                                                        |
| ------------ | ------- | ---------------------------------------------------------------------------------- |
| `token`      | string  | The access token to use in the `Authorization` header for subsequent API requests. |
| `expires_in` | integer | Token validity period in seconds. Default is 900 seconds (15 minutes).             |

Make authenticated requests [#make-authenticated-requests]

Include the access token in the `Authorization` header using the Bearer scheme:

```bash
curl -X GET https://api.fiskil.com/v1/data-provider/cdr/products \
  -H "Authorization: Bearer eyJhbGc...."
```

<Callout type="info">
  Tokens expire after 15 minutes. Implement token refresh logic in your application to obtain new tokens before expiry.
</Callout>

Error responses [#error-responses]

| Status Code             | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `401 Unauthorized`      | Invalid or expired credentials                   |
| `403 Forbidden`         | Insufficient permissions for the requested scope |
| `429 Too Many Requests` | Rate limit exceeded                              |

Invalid credentials [#invalid-credentials]

```json
{
  "error": "invalid_client",
  "error_description": "The client credentials are invalid"
}
```

**Solution:** Verify your client ID and secret are correct and haven't been revoked.

Insufficient permissions [#insufficient-permissions]

```json
{
  "error": "insufficient_scope",
  "error_description": "The access token does not have the required scope"
}
```

**Solution:** Generate new API credentials with the required scopes.

Security best practices [#security-best-practices]

* **Never expose credentials** in client-side code or version control
* **Rotate secrets regularly** and revoke unused credentials
* **Use environment variables** or a secrets manager for credential storage
* **Implement token caching** to reduce authentication requests
* **Monitor API usage** through the Console for unusual activity


---

# Examples (/data-holder/platform-api/examples)

See example payloads to manage different types of products.



Fiskil Platform API allows managing different types of domain-specific products. See below examples how to create products related to specific domains.

Create savings product [#create-savings-product]

```bash title="cURL"
curl -X POST https://api.fiskil.com/v1/data-provider/cdr/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
  "additional_information": {
    "eligibility_uri": "https://www.bank.com/legal/savings-account-target-market-determination/",
    "fees_and_pricing_uri": "https://www.bank.com/legal/savings-rate-fee-guide/",
    "overview_uri": "https://www.bank.com/save/",
    "terms_uri": "https://www.bank.com/legal/terms-conditions-savings/"
  },
  "brand": "Your Bank",
  "brand_name": "Your Bank Brand",
  "description": "Your Bank gets you a fee free, high yield savings account.",
  "is_tailored": false,
  "name": "Savings",
  "product_category": "TRANS_AND_SAVINGS_ACCOUNTS",
  "fees": [
    {
      "name": "Account Keeping Fee",
      "fixed_amount": { "amount": "0.00" },
      "additional_value": "month",
      "fee_type": "PERIODIC",
      "fee_method_u_type": "fixedAmount"
    }
  ],
  "eligibility": [
    {
      "eligibility_type": "NATURAL_PERSON",
      "additional_value": "Not available for joint applicants or non-individual applicants"
    },
    {
      "eligibility_type": "RESIDENCY_STATUS",
      "additional_value": "Individuals must be an Australian Citizen or Permanent Resident"
    },
    {
      "eligibility_type": "MIN_AGE",
      "additional_value": "18"
    }
  ],
  "constraints": [
    {
      "constraint_type": "MAX_BALANCE",
      "additional_value": "250000"
    }
  ],
  "deposit_rates": [
    {
      "deposit_rate_type": "VARIABLE",
      "rate": "0.0415",
      "additional_info_uri": "https://www.bank.com/legal/savings-rate-and-fee-guide/",
      "application_frequency": "P1M",
      "application_type": "PERIODIC",
      "tiers": [
        {
          "maximumValue": "250000.00",
          "minimumValue": "5000.00",
          "name": "Amount",
          "unitOfMeasure": "DOLLAR"
        }
      ]
    }
  ],
  "features": [
    {
      "feature_type": "OTHER",
      "additional_info": "Pay Anyone (Direct Entry)"
    },
    {
      "feature_type": "UNLIMITED_TXNS",
      "additional_info": "Unlimited electronic transactions via Your Bank Online (Internet Banking)"
    },
    {
      "feature_type": "DIGITAL_BANKING",
      "additional_info": "Mobile App"
    },
    {
      "feature_type": "DIGITAL_BANKING",
      "additional_info": "Internet Banking"
    }
  ]
}'
```

```python title="Python"
import requests

url = "https://api.fiskil.com/v1/data-provider/cdr/products"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}
payload = {
    "additional_information": {
        "eligibility_uri": "https://www.bank.com/legal/savings-account-target-market-determination/",
        "fees_and_pricing_uri": "https://www.bank.com/legal/savings-rate-fee-guide/",
        "overview_uri": "https://www.bank.com/save/",
        "terms_uri": "https://www.bank.com/legal/terms-conditions-savings/"
    },
    "brand": "Your Bank",
    "brand_name": "Your Bank Brand",
    "description": "Your Bank gets you a fee free, high yield savings account.",
    "is_tailored": False,
    "name": "Savings",
    "product_category": "TRANS_AND_SAVINGS_ACCOUNTS",
    "fees": [
        {
            "name": "Account Keeping Fee",
            "fixed_amount": {"amount": "0.00"},
            "additional_value": "month",
            "fee_type": "PERIODIC",
            "fee_method_u_type": "fixedAmount"
        }
    ],
    "eligibility": [
        {"eligibility_type": "NATURAL_PERSON", "additional_value": "Not available for joint applicants"},
        {"eligibility_type": "RESIDENCY_STATUS", "additional_value": "Australian Citizen or Permanent Resident"},
        {"eligibility_type": "MIN_AGE", "additional_value": "18"}
    ],
    "constraints": [{"constraint_type": "MAX_BALANCE", "additional_value": "250000"}],
    "deposit_rates": [
        {
            "deposit_rate_type": "VARIABLE",
            "rate": "0.0415",
            "application_frequency": "P1M",
            "application_type": "PERIODIC",
            "tiers": [
                {
                    "maximumValue": "250000.00",
                    "minimumValue": "5000.00",
                    "name": "Amount",
                    "unitOfMeasure": "DOLLAR"
                }
            ]
        }
    ],
    "features": [
        {"feature_type": "OTHER", "additional_info": "Pay Anyone (Direct Entry)"},
        {"feature_type": "UNLIMITED_TXNS", "additional_info": "Unlimited electronic transactions"},
        {"feature_type": "DIGITAL_BANKING", "additional_info": "Mobile App"},
        {"feature_type": "DIGITAL_BANKING", "additional_info": "Internet Banking"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
```

```typescript title="TypeScript"
const url = "https://api.fiskil.com/v1/data-provider/cdr/products";
const headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
};
const payload = {
  additional_information: {
    eligibility_uri: "https://www.bank.com/legal/savings-account-target-market-determination/",
    fees_and_pricing_uri: "https://www.bank.com/legal/savings-rate-fee-guide/",
    overview_uri: "https://www.bank.com/save/",
    terms_uri: "https://www.bank.com/legal/terms-conditions-savings/"
  },
  brand: "Your Bank",
  brand_name: "Your Bank Brand",
  description: "Your Bank gets you a fee free, high yield savings account.",
  is_tailored: false,
  name: "Savings",
  product_category: "TRANS_AND_SAVINGS_ACCOUNTS",
  fees: [{
    name: "Account Keeping Fee",
    fixed_amount: { amount: "0.00" },
    additional_value: "month",
    fee_type: "PERIODIC",
    fee_method_u_type: "fixedAmount"
  }],
  eligibility: [
    { eligibility_type: "NATURAL_PERSON", additional_value: "Not available for joint applicants" },
    { eligibility_type: "RESIDENCY_STATUS", additional_value: "Australian Citizen or Permanent Resident" },
    { eligibility_type: "MIN_AGE", additional_value: "18" }
  ],
  constraints: [{ constraint_type: "MAX_BALANCE", additional_value: "250000" }],
  deposit_rates: [{
    deposit_rate_type: "VARIABLE",
    rate: "0.0415",
    application_frequency: "P1M",
    application_type: "PERIODIC",
    tiers: [
      {
        maximumValue: "250000.00",
        minimumValue: "5000.00",
        name: "Amount",
        unitOfMeasure: "DOLLAR"
      }
    ]
  }],
  features: [
    { feature_type: "OTHER", additional_info: "Pay Anyone (Direct Entry)" },
    { feature_type: "UNLIMITED_TXNS", additional_info: "Unlimited electronic transactions" },
    { feature_type: "DIGITAL_BANKING", additional_info: "Mobile App" },
    { feature_type: "DIGITAL_BANKING", additional_info: "Internet Banking" }
  ]
};

const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(payload)
});
```

Create loan product [#create-loan-product]

```bash title="cURL"
curl -X POST https://api.fiskil.com/v1/data-provider/cdr/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
  "additional_information": {
    "eligibility_uri": "https://www.bank.com/legal/secured-personal-loan-target-market-determination/",
    "fees_and_pricing_uri": "https://www.bank.com/legal/credit-fees-guide/"
  },
  "brand": "Your Bank",
  "brand_name": "Your Bank Brand",
  "description": "Secured personal loan with personalised interest rates.",
  "is_tailored": false,
  "name": "Personal Loan",
  "product_category": "PERS_LOANS",
  "fees": [
    {
      "name": "Establishment fee",
      "fixed_amount": { "amount": "295.00" },
      "fee_type": "UPFRONT",
      "fee_method_u_type": "fixedAmount"
    },
    {
      "name": "Late Payment Fee",
      "fixed_amount": { "amount": "0.00" },
      "fee_type": "EVENT",
      "fee_method_u_type": "fixedAmount"
    },
    {
      "name": "Early Repayment Fee",
      "additional_info": "No penalty for extra repayments or early payout",
      "fixed_amount": { "amount": "0.00" },
      "fee_type": "EVENT",
      "fee_method_u_type": "fixedAmount"
    }
  ],
  "eligibility": [
    {
      "eligibility_type": "NATURAL_PERSON",
      "additional_value": "Not available for joint or non-individual borrowers"
    },
    {
      "eligibility_type": "RESIDENCY_STATUS",
      "additional_value": "Australian Citizen or Permanent Resident"
    },
    {
      "eligibility_type": "MIN_AGE",
      "additional_value": "18"
    }
  ],
  "constraints": [
    { "constraint_type": "MIN_LIMIT", "additional_value": "10000.00" },
    { "constraint_type": "MAX_LIMIT", "additional_value": "100000.00" }
  ],
  "lending_rates": [
    {
      "lending_rate_type": "FIXED",
      "comparison_rate": "0.1217",
      "repayment_type": "PRINCIPAL_AND_INTEREST",
      "rate": "0.1174",
      "additional_info": "Available for 1 to 7 years.",
      "additional_value": "P7Y",
      "application_type": "MATURITY",
      "interest_payment_due": "IN_ARREARS",
      "loan_purpose": "OTHER",
      "tiers": [
        {
          "maximumValue": "250000.00",
          "minimumValue": "5000.00",
          "name": "Amount",
          "unitOfMeasure": "DOLLAR"
        }
      ]
    }
  ],
  "features": [
    {
      "feature_type": "OTHER",
      "additional_info": "No monthly or annual account keeping fees",
      "additional_value": "No ongoing fees"
    },
    {
      "feature_type": "OTHER",
      "additional_info": "Extra repayments or early payout without penalty",
      "additional_value": "No early repayment fees"
    },
    {
      "feature_type": "OTHER",
      "additional_info": "Pay weekly, fortnightly or monthly via direct debit",
      "additional_value": "Repayment frequency"
    }
  ]
}'
```

```python title="Python"
import requests

url = "https://api.fiskil.com/v1/data-provider/cdr/products"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}
payload = {
    "additional_information": {
        "eligibility_uri": "https://www.bank.com/legal/secured-personal-loan-target-market-determination/",
        "fees_and_pricing_uri": "https://www.bank.com/legal/credit-fees-guide/"
    },
    "brand": "Your Bank",
    "brand_name": "Your Bank Brand",
    "description": "Secured personal loan with personalised interest rates.",
    "is_tailored": False,
    "name": "Personal Loan",
    "product_category": "PERS_LOANS",
    "fees": [
        {"name": "Establishment fee", "fixed_amount": {"amount": "295.00"}, "fee_type": "UPFRONT", "fee_method_u_type": "fixedAmount"},
        {"name": "Late Payment Fee", "fixed_amount": {"amount": "0.00"}, "fee_type": "EVENT", "fee_method_u_type": "fixedAmount"},
        {"name": "Early Repayment Fee", "fixed_amount": {"amount": "0.00"}, "fee_type": "EVENT", "fee_method_u_type": "fixedAmount"}
    ],
    "eligibility": [
        {"eligibility_type": "NATURAL_PERSON", "additional_value": "Not available for joint borrowers"},
        {"eligibility_type": "RESIDENCY_STATUS", "additional_value": "Australian Citizen or Permanent Resident"},
        {"eligibility_type": "MIN_AGE", "additional_value": "18"}
    ],
    "constraints": [
        {"constraint_type": "MIN_LIMIT", "additional_value": "10000.00"},
        {"constraint_type": "MAX_LIMIT", "additional_value": "100000.00"}
    ],
    "lending_rates": [{
        "lending_rate_type": "FIXED",
        "comparison_rate": "0.1217",
        "repayment_type": "PRINCIPAL_AND_INTEREST",
        "rate": "0.1174",
        "additional_value": "P7Y",
        "application_type": "MATURITY",
        "interest_payment_due": "IN_ARREARS",
        "tiers": [
            {
                "maximumValue": "250000.00",
                "minimumValue": "5000.00",
                "name": "Amount",
                "unitOfMeasure": "DOLLAR"
            }
        ]
    }],
    "features": [
        {"feature_type": "OTHER", "additional_info": "No ongoing fees", "additional_value": "No ongoing fees"},
        {"feature_type": "OTHER", "additional_info": "No early repayment fees", "additional_value": "No early repayment fees"},
        {"feature_type": "OTHER", "additional_info": "Pay weekly, fortnightly or monthly", "additional_value": "Repayment frequency"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
```

```typescript title="TypeScript"
const url = "https://api.fiskil.com/v1/data-provider/cdr/products";
const headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
};
const payload = {
  additional_information: {
    eligibility_uri: "https://www.bank.com/legal/secured-personal-loan-target-market-determination/",
    fees_and_pricing_uri: "https://www.bank.com/legal/credit-fees-guide/"
  },
  brand: "Your Bank",
  brand_name: "Your Bank Brand",
  description: "Secured personal loan with personalised interest rates.",
  is_tailored: false,
  name: "Personal Loan",
  product_category: "PERS_LOANS",
  fees: [
    { name: "Establishment fee", fixed_amount: { amount: "295.00" }, fee_type: "UPFRONT", fee_method_u_type: "fixedAmount" },
    { name: "Late Payment Fee", fixed_amount: { amount: "0.00" }, fee_type: "EVENT", fee_method_u_type: "fixedAmount" },
    { name: "Early Repayment Fee", fixed_amount: { amount: "0.00" }, fee_type: "EVENT", fee_method_u_type: "fixedAmount" }
  ],
  eligibility: [
    { eligibility_type: "NATURAL_PERSON", additional_value: "Not available for joint borrowers" },
    { eligibility_type: "RESIDENCY_STATUS", additional_value: "Australian Citizen or Permanent Resident" },
    { eligibility_type: "MIN_AGE", additional_value: "18" }
  ],
  constraints: [
    { constraint_type: "MIN_LIMIT", additional_value: "10000.00" },
    { constraint_type: "MAX_LIMIT", additional_value: "100000.00" }
  ],
  lending_rates: [{
    lending_rate_type: "FIXED",
    comparison_rate: "0.1217",
    repayment_type: "PRINCIPAL_AND_INTEREST",
    rate: "0.1174",
    additional_value: "P7Y",
    application_type: "MATURITY",
    interest_payment_due: "IN_ARREARS",
    tiers: [
      {
        maximumValue: "250000.00",
        minimumValue: "5000.00",
        name: "Amount",
        unitOfMeasure: "DOLLAR"
      }
    ]
  }],
  features: [
    { feature_type: "OTHER", additional_info: "No ongoing fees", additional_value: "No ongoing fees" },
    { feature_type: "OTHER", additional_info: "No early repayment fees", additional_value: "No early repayment fees" },
    { feature_type: "OTHER", additional_info: "Pay weekly, fortnightly or monthly", additional_value: "Repayment frequency" }
  ]
};

const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(payload)
});
```


---

# Introduction (/data-holder/platform-api/introduction)

Programmatically manage your Fiskil Data Provider platform resources.



The Platform API provides programmatic access to administrative functions on the Fiskil Data Provider platform. Use these APIs to automate product management, integrate with your CI/CD pipelines, and build custom tooling.

Available APIs [#available-apis]

<CardGroup cols={2}>
  <Card title="Products API" icon="box" href="/data-holder/platform-api/createProduct">
    Create, update, list, and delete CDR banking products.
  </Card>

  <Card title="Consents API" icon="file-signature" href="/data-holder/platform-api/listConsents">
    List and manage consents authorized by your customers.
  </Card>
</CardGroup>

Base URL [#base-url]

```
https://api.fiskil.com/v1/data-provider
```

OpenAPI Specification [#openapi-specification]

Download the full OpenAPI specification for the Platform API to generate clients, import into API tooling, or browse the schema offline.

<Card title="Download Platform OpenAPI Spec" icon="download" href="/openapi/holder-platform-api.json">
  Get the latest Platform API OpenAPI 3.0 specification.
</Card>


---

# Monitoring & Logs (/data-api/guides/account-access/monitoring-and-logs)

Understand how to monitor webhook deliveries and implement logging practices to keep your integration reliable.



The Fiskil platform gives you clear visibility into activity across your account and API usage. Logs help you track changes, investigate issues, and maintain security and compliance. Fiskil provides multiple log types, **audit logs** for console actions, **request logs** for incoming API traffic, and **webhook logs** for outgoing API traffic, offering a complete view of your platform's operations.

Log Types [#log-types]

Fiskil provides multiple categories of logs to help you monitor activity, troubleshoot issues, and maintain visibility into your platform usage:

| Log Type         | Description                                                                                                                         | Typical Use Cases                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Audit Logs**   | Capture changes made in the Fiskil Console, such as billing updates, team management actions, or configuration changes.             | Security auditing, compliance tracking, change history.         |
| **Request Logs** | Record incoming API requests made to the Fiskil platform using your API keys, including endpoint, method, status code, and latency. | Performance monitoring, debugging, traffic analysis.            |
| **Webhook Logs** | Track outgoing webhook deliveries from Fiskil to your systems, including payload content, delivery attempts, and response status.   | Integration debugging, delivery confirmation, error resolution. |

All logs can be viewed in the Fiskil Console. Exporting or log draining is not currently supported.

Audit Logs [#audit-logs]

Audit logs can be viewed in the Fiskil Console under [Settings > Data API > Audit Logs](https://console.fiskil.com). It is only available to team users with `owner` role.
The following table lists the currently logged audit events, their categories, and descriptions.

| Event                                    | Category               | Description                                                                     |
| ---------------------------------------- | ---------------------- | ------------------------------------------------------------------------------- |
| `billing.payment_method.added`           | Billing Management     | When a new payment method is added to an account.                               |
| `billing.payment_method.deleted`         | Billing Management     | When an existing payment method is removed from the account.                    |
| `billing.payment_method.default_changed` | Billing Management     | When the default payment method is changed to a different one.                  |
| `branding.consent_flow.updated`          | Platform Configuration | When any consent UI settings under "Customize UI" are modified.                 |
| `api_key.created`                        | Platform Configuration | When a new API key is generated for accessing the platform programmatically.    |
| `api_key.deleted`                        | Platform Configuration | When an existing API key is deleted and access is revoked.                      |
| `webhook.added`                          | Platform Configuration | When a new webhook is registered to receive system events.                      |
| `webhook.deleted`                        | Platform Configuration | When a webhook is removed from the configuration.                               |
| `team_member.invited`                    | Team Management        | When a new team member is invited to join a team.                               |
| `team.member.added`                      | Team Management        | When a new team member accepts the invitation.                                  |
| `team.member.removed`                    | Team Management        | When a team member is removed from the team.                                    |
| `team.member.updated`                    | Team Management        | When a team member's role or permissions are updated.                           |
| `team.information.updated`               | Team Management        | When team settings (contacts, company) are changed.                             |
| `auth.mfa.added`                         | Authentication         | When multi-factor authentication (e.g. SMS or phone) is enabled for an account. |
| `auth.mfa.removed`                       | Authentication         | When multi-factor authentication is disabled or removed.                        |
| `auth.user.logged_in`                    | Authentication         | When a user logs into the Fiskil platform or switches teams.                    |

Request Logs [#request-logs]

Request logs record incoming API requests made to the Fiskil platform using your API keys.
They are retained for **90 days** and can be viewed in the Fiskil Console under the **Logs** tab.

For each request, the Console displays:

* **Endpoint & Method** -- e.g., `GET /banking/accounts`.
* **Team ID** and **End User ID** (if provided).
* **Timestamp** -- When the request was received.
* **Status Code** -- The HTTP status code returned.
* **IP Address** -- Source of the request.
* **User Agent** -- The client making the request.
* **Response Size** and **Latency**.

Logs can be filtered by date range, end\_user\_id and path. These logs help you debug requests, analyze API performance, and monitor traffic patterns.

Webhook Logs [#webhook-logs]

Webhook logs record outgoing webhook deliveries from the Fiskil platform to your configured endpoints.
They are retained for **90 days** and can be viewed in the Fiskil Console by navigating to **[Settings > Webhooks](https://console.fiskil.com)** and selecting a registered webhook.

For each webhook endpoint, the Console displays:

* **Recent Events** -- A list of events delivered to the endpoint.
* **Delivery Status** -- Whether the delivery was successful or failed.
* **Response Status Code** -- The HTTP status code returned by your server.
* **Timestamp** -- When the delivery attempt was made.

This visibility helps you quickly identify and resolve integration issues, such as:

* Unreachable or misconfigured endpoints.
* Unexpected `4xx` or `5xx` responses.
* Delivery retries due to timeouts or failures.

Recommended Logging on Your Side [#recommended-logging-on-your-side]

To better support observability, and troubleshooting within your own application, we recommend logging the following:

* All incoming webhook payloads (excluding sensitive fields)
* Response status codes your server returns
* Any webhook verification failures (e.g. invalid signature)
* Internal processing outcomes (e.g. sync success, validation errors)

Your logs should include:

* `message_id` from the webhook payload (for deduplication and tracing)
* `event` name (e.g. `transactions.sync.completed`)
* Timestamps for when your system processed each event

These logs will be essential when debugging failed syncs or investigating data availability issues.

Recommendations for Monitoring [#recommendations-for-monitoring]

To get the most value from Fiskil's monitoring and logging capabilities, we recommend the following best practices:

* **Regularly review audit logs** to track account changes and ensure compliance with organizational policies.
* **Monitor request logs** to detect performance bottlenecks, unusual traffic patterns, or failed API calls that may indicate issues or misuse.
* **Check webhook logs frequently** to verify successful deliveries and promptly resolve integration problems.
* **Secure access to logs** by restricting viewing permissions to authorized team members, maintaining data privacy and integrity.

Following these practices helps maintain operational visibility, detect issues early, and support security and compliance efforts effectively.

Related Guides [#related-guides]

* [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks)
* [Security](/docs/data-api/guides/account-access/security)
* [Support & Troubleshooting](/docs/data-api/guides/support/troubleshooting)


---

# Security (/data-api/guides/account-access/security)

Fiskil provides multiple layers of security to protect your Console account and manage access to sensitive data.



Fiskil provides multiple layers of security to protect your Console account and manage access to sensitive data. This page outlines authentication methods, session policies, and account protection guidance.

Password Recovery [#password-recovery]

If you forget your password, use the Forgot password link on the Console login page to initiate a secure reset process.

You'll receive an email with a link to update your password. If your email address hasn't been verified, you'll need to complete that step before resetting your password.

All password updates must be done via this flow — there is no in-app password change feature.

Multi-Factor Authentication (MFA) [#multi-factor-authentication-mfa]

MFA is enforced for all users of the Fiskil Console.

During login, you'll be required to enter a time-based one-time password (TOTP) from a supported authenticator app such as Google Authenticator or Authy.

MFA is mandatory and cannot be disabled.

Session Expiry [#session-expiry]

Fiskil Console sessions expire automatically after **2 hours** of inactivity. Once expired, users are logged out and prompted to re-authenticate using MFA.

SSO Support [#sso-support]

Fiskil supports Single Sign-On (SSO) for teams that use enterprise identity providers such as Okta, Google Workspaces, or Azure AD.

SSO must be enabled by our support team. For configuration details and supported providers, see the [SSO Login guide](/data-api/guides/account-access/sso-login).

Best Practices [#best-practices]

* Avoid exposing API keys or tokens in frontend code
* Remove unused team members promptly
* Secure your MFA recovery codes
* Use a strong, unique password

If you suspect unauthorised access to your account, contact [Fiskil Support](https://fiskil.atlassian.net/servicedesk/customer/portal/6) immediately.


---

# Team & Roles (/data-api/guides/account-access/team-and-roles)

Manage workspace access by inviting team members and assigning role-based permissions.



Fiskil allows you to manage access to your workspace by inviting team members and assigning role-based permissions through the Console.

This guide outlines the available roles and how to manage team members securely and effectively.

Managing Team Members [#managing-team-members]

You can view and manage your team from the **[Console > Settings > Members](https://console.fiskil.com)** page.

From here, you can:

* View the status of pending invitations
* Remove users who no longer require access
* Assign roles during or after invitation
* Invite new users to your team by email

Team changes take effect immediately. All team members must authenticate using MFA when accessing the Console.

Supported Roles [#supported-roles]

Fiskil currently supports three roles, each with different levels of access:

| Role      | Permissions                                                              |
| --------- | ------------------------------------------------------------------------ |
| Owner     | Full access to all settings, API keys, team management, and billing      |
| Developer | Can view and manage API keys, webhooks, and data - no team permissions   |
| Analyst   | Read-only access to data and dashboards - cannot modify settings or keys |

You can change a user's role at any time via the Members page.

For security reasons, only Owners can invite new members or manage team roles.

Best Practices [#best-practices]

* Revoke access promptly when a team member no longer needs access
* Regularly review your team to ensure access levels are up to date
* Use the Analyst role for data consumers who don't need write access
* Assign the Owner role only to trusted administrators

Related Guides [#related-guides]

* [SSO Login](/docs/data-api/guides/account-access/sso-login)
* [Security](/docs/data-api/guides/account-access/security)


---

# Overview (/data-api/guides/ai-tools)

Use AI assistants to build Fiskil integrations faster



Fiskil provides optimized resources for AI-assisted development. Copy the
prompt below into your AI assistant to get a complete integration built in
minutes.

Two ways to get started [#two-ways-to-get-started]

Pick the option that fits your workflow:

1. **Copy the integration prompt** (recommended) — paste it into Cursor,
   Claude Code, ChatGPT, or any AI coding assistant
2. **Connect the MCP server** — gives your AI tool live access to Fiskil
   documentation. See [MCP server setup](/data-api/guides/ai-tools/mcp)

Fiskil integration prompt [#fiskil-integration-prompt]

Copy everything inside the code fence and paste it as context for your AI
assistant.

```markdown
# Fiskil Data API — Complete Integration Guide

Fiskil is a CDR (Consumer Data Right) platform for accessing consumer
banking and energy data with consent. You integrate once and get access to
banking transactions, account details, and energy usage data.

## API Basics

- Base URL: https://api.fiskil.com/v1
- Auth: Bearer token from POST /v1/token
- All API calls must be server-side — never expose credentials in frontend

## Authentication

POST /v1/token
Content-Type: application/json

{ "client_id": "...", "client_secret": "..." }

Response: { "token": "...", "token_type": "Bearer", "expires_in": 900 }

Store credentials in environment variables. Cache tokens until near expiry.

## Core Flow

1. Create End User → POST /v1/end-users { email, name, phone? }
2. Create Auth Session → POST /v1/auth/session { end_user_id, cancel_uri }
3. Frontend: Open Link SDK with session_id
4. User completes consent flow
5. Backend: Receive webhook events
6. Backend: Fetch data using consent_id

## Create End User

POST /v1/end-users
Authorization: Bearer {token}
Content-Type: application/json

{ "email": "user@example.com", "name": "User Name", "phone": "+1234567890" }

Response: { "id": "end_user_abc123", "email": "...", "name": "..." }

Store the id — needed for auth sessions.

## Create Auth Session

POST /v1/auth/session
Authorization: Bearer {token}
Content-Type: application/json

{ "end_user_id": "end_user_abc123", "cancel_uri": "https://yourapp.com/cancel" }

Response: { "session_id": "sess_xyz789", "auth_url": "...", "expires_at": "..." }

Pass session_id to the Link SDK in your frontend.

## Frontend: Link SDK (@fiskil/link)

The Link SDK embeds a consent UI for users to connect their bank or energy
accounts.

### Installation

npm install @fiskil/link

### API

link(sessionId, options?) returns a LinkFlow which is:

- A Promise resolving to { consentID?: string, redirectURL?: string }
- A controller with .close() to cancel programmatically

Options:

- timeoutMs: number — timeout in ms (default: 600000 / 10 min)

### Basic usage

import { link, LinkError } from '@fiskil/link';

async function startLink(authSessionId: string) {
const flow = link(authSessionId);

try {
const result = await flow;
console.log('Consent ID:', result.consentID);
return result.consentID;
} catch (err) {
const error = err as LinkError;
handleLinkError(error);
throw error;
}
}

// Cancel programmatically if needed
// flow.close();

## Handle Link Errors

The SDK rejects with LinkError containing a code property:

interface LinkError extends Error {
name: 'LinkError';
code: LinkErrorCode;
details?: unknown;
}

Error codes and how to handle them:

| Code                              | Description                             | User Message                                                 |
| --------------------------------- | --------------------------------------- | ------------------------------------------------------------ |
| LINK_USER_CANCELLED               | User closed the flow or .close() called | "You cancelled the linking process."                         |
| LINK_TIMEOUT                      | Flow exceeded timeoutMs                 | "The session timed out. Please try again."                   |
| LINK_INVALID_SESSION              | Invalid auth_session_id                 | "Invalid session. Please restart the process."               |
| LINK_ORIGIN_MISMATCH              | Message from unexpected origin          | "Security error. Please try again."                          |
| LINK_NOT_FOUND                    | Container element not in DOM            | "Display error. Please refresh and try again."               |
| LINK_INTERNAL_ERROR               | Unrecognized SDK error                  | "An error occurred. Please try again."                       |
| CONSENT_ENDUSER_DENIED            | User denied consent                     | "You declined to share your data."                           |
| CONSENT_OTP_FAILURE               | OTP verification failed                 | "Verification failed. Please try again."                     |
| CONSENT_ENDUSER_INELIGIBLE        | User ineligible for sharing             | "Your account is not eligible for data sharing."             |
| CONSENT_TIMEOUT                   | Consent process timed out               | "The consent process timed out. Please try again."           |
| CONSENT_UPSTREAM_PROCESSING_ERROR | Bank/provider error                     | "There was an issue with your bank. Please try again later." |

function handleLinkError(error: LinkError): string {
switch (error.code) {
case 'LINK_USER_CANCELLED':
return 'You cancelled the linking process.';
case 'LINK_TIMEOUT':
case 'CONSENT_TIMEOUT':
return 'The session timed out. Please try again.';
case 'LINK_INVALID_SESSION':
return 'Invalid session. Please restart the process.';
case 'CONSENT_ENDUSER_DENIED':
return 'You declined to share your data.';
case 'CONSENT_OTP_FAILURE':
return 'Verification failed. Please try again.';
case 'CONSENT_ENDUSER_INELIGIBLE':
return 'Your account is not eligible for data sharing.';
case 'CONSENT_UPSTREAM_PROCESSING_ERROR':
return 'There was an issue with your bank. Please try again later.';
default:
return 'An error occurred. Please try again.';
}
}

## Webhooks

Register endpoints in Fiskil Console. Key events:

| Event                               | When to fetch data     |
| ----------------------------------- | ---------------------- |
| consent.received                    | User completed consent |
| banking.transactions.sync.completed | Banking data ready     |
| energy.usage.sync.completed         | Energy data ready      |

Webhook payload structure:
{
"event": "banking.transactions.sync.completed",
"data": { "consent_id": "..." },
"message_id": "unique-id-for-idempotency"
}

Verify signature with X-Fiskil-Signature header (HMAC-SHA256).

## Fetch Data

After receiving sync webhooks:

GET /v1/accounts?consent_id={consent_id}
GET /v1/transactions?consent_id={consent_id}
GET /v1/energy/usage?consent_id={consent_id}

## Full TypeScript Example

class FiskilClient {
private baseUrl = 'https://api.fiskil.com/v1';
private token: string | null = null;
private tokenExpiry = 0;

private async getToken(): Promise<string> {
if (this.token && Date.now() < this.tokenExpiry - 60000) {
return this.token;
}
const res = await fetch(`${this.baseUrl}/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
client_id: process.env.FISKIL_CLIENT_ID,
client_secret: process.env.FISKIL_CLIENT_SECRET,
}),
});
const data = await res.json();
this.token = data.token;
this.tokenExpiry = Date.now() + data.expires_in \* 1000;
return this.token;
}

private async request<T>(endpoint: string, options?: RequestInit): Promise<T> {
const token = await this.getToken();
const res = await fetch(`${this.baseUrl}${endpoint}`, {
...options,
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
...options?.headers,
},
});
if (!res.ok) throw new Error(`Fiskil API error: ${res.status}`);
return res.json();
}

createEndUser(data: { email: string; name: string; phone?: string }) {
return this.request<{ id: string }>('/end-users', {
method: 'POST',
body: JSON.stringify(data),
});
}

createAuthSession(endUserId: string, cancelUri: string) {
return this.request<{ session_id: string }>('/auth/session', {
method: 'POST',
body: JSON.stringify({ end_user_id: endUserId, cancel_uri: cancelUri }),
});
}

getAccounts(consentId: string) {
return this.request<{ accounts: any[] }>(`/accounts?consent_id=${consentId}`);
}

getTransactions(consentId: string) {
return this.request<{ transactions: any[] }>(`/transactions?consent_id=${consentId}`);
}
}

## React Component Pattern

'use client';

import { useState, useCallback, useRef } from 'react';
import { link, LinkError, LinkErrorCode } from '@fiskil/link';

type LinkStatus = 'idle' | 'linking' | 'success' | 'error';

interface UseLinkAccountResult {
startLink: (sessionId: string) => Promise<string | null>;
cancel: () => void;
status: LinkStatus;
error: { code: LinkErrorCode; message: string } | null;
}

export function useLinkAccount(): UseLinkAccountResult {
const [status, setStatus] = useState<LinkStatus>('idle');
const [error, setError] = useState<{ code: LinkErrorCode; message: string } | null>(null);
const flowRef = useRef<ReturnType<typeof link> | null>(null);

const startLink = useCallback(async (sessionId: string): Promise<string | null> => {
setStatus('linking');
setError(null);

    try {
      const flow = link(sessionId);
      flowRef.current = flow;
      const result = await flow;
      setStatus('success');
      return result.consentID ?? null;
    } catch (err) {
      const linkError = err as LinkError;
      if (linkError.code === 'LINK_USER_CANCELLED') {
        setStatus('idle');
        return null;
      }
      setStatus('error');
      setError({ code: linkError.code, message: handleLinkError(linkError) });
      return null;
    } finally {
      flowRef.current = null;
    }

}, []);

const cancel = useCallback(() => {
flowRef.current?.close();
}, []);

return { startLink, cancel, status, error };
}

// Example component
function LinkAccountButton({
sessionId,
onSuccess
}: {
sessionId: string;
onSuccess: (consentId: string) => void;
}) {
const { startLink, status, error } = useLinkAccount();

const handleClick = async () => {
const consentId = await startLink(sessionId);
if (consentId) onSuccess(consentId);
};

return (
<div>
{error && <p className="text-red-600">{error.message}</p>}
<button onClick={handleClick} disabled={status === 'linking'}>
{status === 'linking' ? 'Connecting...' : 'Link Account'}
</button>
</div>
);
}

## Webhook Handler Example (Next.js)

import crypto from 'crypto';
import { NextRequest, NextResponse } from 'next/server';

const WEBHOOK_SECRET = process.env.FISKIL_WEBHOOK_SECRET!;

function verifySignature(payload: string, signature: string): boolean {
const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

export async function POST(req: NextRequest) {
const signature = req.headers.get('x-fiskil-signature');
const payload = await req.text();

if (!signature || !verifySignature(payload, signature)) {
return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
}

const { event, data, message_id } = JSON.parse(payload);

// Idempotency check
if (await isProcessed(message_id)) {
return NextResponse.json({ status: 'already processed' });
}

switch (event) {
case 'consent.received':
await handleConsentReceived(data);
break;
case 'banking.transactions.sync.completed':
await fetchAndStoreBankingData(data.consent_id);
break;
case 'energy.usage.sync.completed':
await fetchAndStoreEnergyData(data.consent_id);
break;
}

await markProcessed(message_id);
return NextResponse.json({ status: 'ok' });
}

## Security Checklist

- [ ] Credentials in environment variables only
- [ ] All API calls server-side
- [ ] Tokens never logged or exposed
- [ ] Webhook signatures verified
- [ ] Idempotency on webhook handlers (use message_id)
- [ ] HTTPS for all endpoints
```

Other resources [#other-resources]

| Resource                         | Description                             |
| -------------------------------- | --------------------------------------- |
| [/llms.txt](/llms.txt)           | Directory of all documentation pages    |
| [/llms-full.txt](/llms-full.txt) | Complete documentation as a single file |
| [/skill.md](/skill.md)           | Fiskil capabilities summary             |

Every documentation page is also available as raw markdown by appending
`.mdx` to the URL. For example:
`/data-api/guides/getting-started/quick-start.mdx`


---

# MCP Server (/data-api/guides/ai-tools/mcp)

Connect AI tools directly to Fiskil documentation using Model Context Protocol



import { Callout } from 'fumadocs-ui/components/callout';

The Fiskil MCP server gives your AI assistant direct access to Fiskil documentation, API references, and code examples. It works with any editor or tool that supports [Model Context Protocol](https://modelcontextprotocol.io/) — including Cursor, Claude Code, Windsurf, and VS Code Copilot.

**What your AI assistant can do once connected:**

* Full-text search across all documentation
* Retrieve complete page content including API reference details
* Browse the documentation tree by product and section
* Look up API endpoint details with request/response schemas
* Get copy-paste code examples in TypeScript, Python, JavaScript, and cURL
* Follow guided prompts for onboarding and integration

Server URL [#server-url]

```
https://docs.fiskil.com/api/ai/mcp
```

Setup [#setup]

Cursor [#cursor]

Copy this to your `.cursor/mcp.json` file:

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "fiskil": {
      "url": "https://docs.fiskil.com/api/ai/mcp"
    }
  }
}
```

Restart Cursor to apply changes. If you use the Cursor CLI (`agent`), it reads the same `mcp.json` automatically — no separate setup is needed.

Claude Code [#claude-code]

Claude Code is Anthropic's terminal CLI (`claude`). Use the one-liner, or copy the JSON into your config file:

<Tabs items={['CLI', 'JSON']}>
  <Tab value="CLI">
    ```bash
    claude mcp add --transport http fiskil https://docs.fiskil.com/api/ai/mcp
    ```

    This scopes the server to the current project. Add `--scope user` to make it available globally. Confirm with `claude mcp list`.
  </Tab>

  <Tab value="JSON">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "fiskil": {
          "type": "http",
          "url": "https://docs.fiskil.com/api/ai/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

For the JSON option, save to `.mcp.json` in your project root (project-scoped) or `~/.claude.json` (global).

VS Code Copilot [#vs-code-copilot]

<Tabs items={['CLI', 'JSON']}>
  <Tab value="CLI">
    ```bash
    code --add-mcp "{\"name\":\"fiskil\",\"type\":\"http\",\"url\":\"https://docs.fiskil.com/api/ai/mcp\"}"
    ```

    This adds the server to your user profile, so it is available across all your workspaces. For a workspace-only setup, use the JSON option instead.
  </Tab>

  <Tab value="JSON">
    ```json title=".vscode/mcp.json"
    {
      "servers": {
        "fiskil": {
          "type": "http",
          "url": "https://docs.fiskil.com/api/ai/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Copy the JSON to `.vscode/mcp.json` in your workspace, or use **MCP: Open User Configuration** from the Command Palette for a global entry. VS Code uses a `servers` key (not `mcpServers`) and requires `"type": "http"` for remote servers.

Windsurf [#windsurf]

Windsurf has no CLI for adding servers. Copy this to `~/.codeium/windsurf/mcp_config.json`:

```json title="mcp_config.json"
{
  "mcpServers": {
    "fiskil": {
      "serverUrl": "https://docs.fiskil.com/api/ai/mcp"
    }
  }
}
```

<Callout type="info">
  Windsurf uses `serverUrl` instead of `url` for remote MCP servers.
</Callout>

Other MCP Clients [#other-mcp-clients]

Any MCP-compatible client can connect using the server URL above. Consult your client's documentation for configuration instructions.

***

Tools [#tools]

The MCP server provides six tools that your AI assistant can call.

search_docs [#search_docs]

Full-text search across Fiskil documentation. Searches page titles, headings, and body content. Returns matching pages with relevant text snippets and direct URLs.

| Parameter | Type   | Required | Default | Description                                            |
| --------- | ------ | -------- | ------- | ------------------------------------------------------ |
| `query`   | string | Yes      | —       | Search query to find relevant documentation            |
| `product` | string | No       | `all`   | Filter by product: `all`, `data-api`, or `data-holder` |
| `limit`   | number | No       | `10`    | Maximum number of results (1–20)                       |

**Example prompts:**

> "Search Fiskil docs for webhook signature verification"
>
> "Search for authentication in the Data API docs, limit to 5 results"

Each result includes a `fullUrl` field with the absolute URL you can open directly in your browser.

***

get_page [#get_page]

Retrieve the full markdown content of a specific documentation page. For API reference pages, this includes the HTTP method, path, parameters, request/response schemas, and examples.

| Parameter | Type   | Required | Description                                                               |
| --------- | ------ | -------- | ------------------------------------------------------------------------- |
| `path`    | string | Yes      | URL path of the page, e.g. `/data-api/guides/getting-started/quick-start` |

**Example prompts:**

> "Get the full content of the Fiskil authentication guide"
>
> "Fetch the page at /data-api/guides/core-concepts/webhooks"

<Callout type="info">
  If the page is not found, the response will suggest using `search_docs` or `list_pages` to discover valid paths.
</Callout>

***

list_pages [#list_pages]

Browse the documentation tree. Returns all available pages grouped by product and section. Use this to discover what documentation exists before searching or fetching specific pages.

| Parameter | Type   | Required | Default | Description                                                         |
| --------- | ------ | -------- | ------- | ------------------------------------------------------------------- |
| `product` | string | No       | `all`   | Filter by product: `all`, `data-api`, or `data-holder`              |
| `section` | string | No       | `all`   | Filter by section: `all`, `guides`, `api-reference`, or `changelog` |

**Example prompts:**

> "List all Fiskil Data API guide pages"
>
> "Show me the API reference pages for Data API"

***

list_api_endpoints [#list_api_endpoints]

List API endpoints from the Fiskil OpenAPI reference. Returns the HTTP method, path, summary, operationId, and tags for each endpoint.

| Parameter  | Type   | Required | Default | Description                                                                                                 |
| ---------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `product`  | string | No       | `all`   | Filter by product: `all`, `data-api`, or `data-holder`                                                      |
| `category` | string | No       | —       | Filter by category/tag (case-insensitive), e.g. `Banking`, `Energy`, `auth`, `Common`, `cdr`, `fdx`, `psd2` |

**Example prompts:**

> "List all Fiskil banking API endpoints"
>
> "Show me the energy endpoints in the Data API"

<Callout type="info">
  Data Holder endpoints (CDR, FDX, PSD2) are currently in preview. If Data Holder is not yet enabled for your environment, the tool will let you know and suggest contacting Fiskil for early access.
</Callout>

***

get_api_endpoint_details [#get_api_endpoint_details]

Look up detailed information for a specific API endpoint. Returns parameters, request/response schemas with field-level descriptions, examples, and a ready-to-use cURL snippet.

You can look up an endpoint in two ways:

1. **By method + path** — e.g. `GET /v1/accounts`
2. **By operationId** — e.g. `getBankingTransactions` or `add-auth-session`

| Parameter     | Type   | Required    | Default    | Description                                                                               |
| ------------- | ------ | ----------- | ---------- | ----------------------------------------------------------------------------------------- |
| `method`      | string | Conditional | —          | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Required when using path lookup. |
| `path`        | string | Conditional | —          | API path, e.g. `/v1/token` or `/v1/accounts`                                              |
| `operationId` | string | Conditional | —          | Operation ID or slug, e.g. `getBankingTransactions`. Alternative to method + path.        |
| `product`     | string | No          | `data-api` | Which product to search: `data-api` or `data-holder`                                      |

<Callout type="info">
  You must provide **either** `method` + `path` **or** `operationId`. The operationId supports both camelCase (`getBankingAccounts`) and kebab-case (`get-banking-accounts`) formats.
</Callout>

**Example prompts:**

> "Get details for GET /v1/accounts from Fiskil"
>
> "Look up the getBankingTransactions endpoint"
>
> "Show me the request and response schema for POST /v1/auth/session"

If the endpoint is not found, the tool suggests similar endpoints you might have meant.

***

get_code_examples [#get_code_examples]

Get copy-paste code examples for common Fiskil integration patterns. Available in TypeScript, Python, JavaScript, and cURL.

| Parameter  | Type   | Required | Default       | Description                                                                                                   |
| ---------- | ------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------------- |
| `topic`    | string | Yes      | —             | Integration topic: `auth`, `end-users`, `auth-session`, `link-sdk`, `webhooks`, `banking`, `energy`, or `all` |
| `language` | string | No       | all languages | Programming language: `typescript`, `python`, `javascript`, or `curl`                                         |

**Available topics:**

| Topic          | What it covers                                          |
| -------------- | ------------------------------------------------------- |
| `auth`         | Authenticate with client credentials (`POST /v1/token`) |
| `end-users`    | Create end users                                        |
| `auth-session` | Create auth sessions for the Link SDK                   |
| `link-sdk`     | Embed the Link SDK in React/JavaScript                  |
| `webhooks`     | Webhook verification and event handling                 |
| `banking`      | Fetch banking data (accounts, transactions, balances)   |
| `energy`       | Fetch energy data (usage, billing, service points)      |
| `all`          | All of the above                                        |

**Example prompts:**

> "Show me a TypeScript example for Fiskil authentication"
>
> "Get Python code examples for handling webhooks"
>
> "Show all Fiskil banking code examples"

***

Prompts [#prompts]

The MCP server includes two guided prompts that provide structured workflows. Your AI assistant can use these to give you step-by-step guidance.

fiskil_getting_started [#fiskil_getting_started]

A recommended workflow for new developers integrating with Fiskil APIs. No parameters required.

Walks you through a 6-step onboarding process:

1. **Authenticate** — get an access token with client credentials
2. **Create an End User** — register the user who will link their accounts
3. **Create an Auth Session** — generate a session for the Link SDK
4. **Embed the Link SDK** — install and launch the consent flow in your app
5. **Set Up Webhooks** — listen for data sync events with signature verification
6. **Fetch Data** — use the consent ID to call banking or energy data endpoints

**Example prompt:**

> "Use the Fiskil getting started guide to walk me through integration"

fiskil_integration_guide [#fiskil_integration_guide]

A tailored integration guide filtered by your use case. Returns relevant API endpoints, webhook events, and implementation guidance.

| Parameter  | Type   | Required | Description                                              |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| `use_case` | string | Yes      | The data domain you need: `banking`, `energy`, or `both` |

**What's included by use case:**

* **banking** — Accounts, Transactions, Balances, Payees, Direct Debits, Scheduled Payments endpoints + `banking.transactions.sync.completed` webhook
* **energy** — Energy Accounts, Usage, Billing, Service Points, DER, Concessions endpoints + `energy.usage.sync.completed` webhook
* **both** — All of the above

**Example prompt:**

> "Give me the Fiskil integration guide for banking"

***

Resources [#resources]

docs://overview [#docsoverview]

The MCP server exposes a documentation overview resource at `docs://overview`. This provides a summary of:

* Available products (Data API, Data Holder) with page counts
* All available MCP tools and prompts
* Quick links to key documentation pages
* Links to LLM resources

***

Usage Tips [#usage-tips]

1. **Start with search** — ask your AI to search for topics rather than guessing page URLs
2. **Browse first** — use `list_pages` to discover what documentation is available
3. **Get full pages** — once you find relevant results, use `get_page` for the complete content
4. **Look up endpoints** — use `list_api_endpoints` to find endpoints, then `get_api_endpoint_details` for schemas and examples
5. **Grab code snippets** — use `get_code_examples` to get working starter code in your language
6. **Follow guided prompts** — use the getting started or integration guide prompts for a structured walkthrough
7. **Combine with the integration prompt** — use MCP alongside the [Fiskil Integration Prompt](/data-api/guides/ai-tools) for best results

***

Troubleshooting [#troubleshooting]

Connection Issues [#connection-issues]

If your AI tool can't connect to the MCP server:

1. Verify the server URL is exactly `https://docs.fiskil.com/api/ai/mcp`
2. Check that your network allows outbound HTTPS connections
3. Restart your AI application after making configuration changes
4. For Windsurf, make sure you're using `serverUrl` (not `url`) in the config
5. **Verify registration** — run `claude mcp list` (Claude Code) or `agent mcp list` (Cursor CLI) to confirm the server appears in the list

No Results [#no-results]

If searches return no results:

1. Try broader or different search terms
2. Use the `product` filter to narrow scope (e.g., `data-api`)
3. Use `list_pages` to browse available documentation
4. Check [`/llms.txt`](https://docs.fiskil.com/llms.txt) for a list of all available pages

Rate Limiting [#rate-limiting]

The MCP server allows up to **100 requests per minute**. If you exceed this limit, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating how long to wait before retrying.

***

LLM Resources [#llm-resources]

In addition to MCP, the following resources are available for AI tools:

| Resource        | URL                                                     | Description                                  |
| --------------- | ------------------------------------------------------- | -------------------------------------------- |
| `llms.txt`      | [/llms.txt](https://docs.fiskil.com/llms.txt)           | Lightweight index of all documentation pages |
| `llms-full.txt` | [/llms-full.txt](https://docs.fiskil.com/llms-full.txt) | Full documentation content in a single file  |
| `skill.md`      | [/skill.md](https://docs.fiskil.com/skill.md)           | Integration prompt for AI assistants         |

***

Security [#security]

The MCP server provides **read-only** access to public documentation. No authentication is required, and no sensitive data is exposed.


---

# Auth Sessions (/data-api/guides/core-concepts/auth-sessions)

Temporary sessions used to initiate Fiskil's consent flow



An Auth Session is a temporary session used to initiate Fiskil's consent flow. It enables your users to securely authenticate with their financial or energy institution and approve access to their data.

Once you create an Auth Session, you'll receive an `auth_url` that launches Fiskil's hosted consent UI. The recommended way to present this is using the Fiskil Link SDK, which embeds the consent flow inside your app with a single function call.

<Callout type="info">
  Note: An Auth Session will expire after 5 days and the user must complete the consent flow within this time frame.
</Callout>

Integration Flows [#integration-flows]

1. Link SDK (Recommended) [#1-link-sdk-recommended]

The [Link SDK](https://github.com/Fiskil/link/) is the easiest way to keep users inside your app while completing the consent experience. Instead of manually embedding iframes and listening for postMessage events, install `@fiskil/link` and pass in the auth\_session\_id returned by the API. The SDK renders the consent flow and resolves with the result.

```javascript
import { link } from '@fiskil/link';

const flow = link('auth_session_id');

try {
  const result = await flow;
  console.log(result.consentID);
} catch (err) {
  console.error('Link error:', err);
}
```

See [Integrating the Link SDK](/data-api/guides/link-widget/integrating-the-link-sdk) for full details.

2. Redirect Flow [#2-redirect-flow]

The default approach is to *redirect your user to the `auth_url`* in the current browser tab or window.

* The user completes the consent journey hosted on Fiskil's domain.
* On success, they are redirected to your configured `redirect_uri`.
* On failure or cancellation, they are redirected to your configured `cancel_uri`. In this case, *error details will be included in the query parameters*, following Fiskil's [error type format](/data-api/api-reference/errors).
* Use this flow for quick integrations where maintaining in-app context isn't required.

3. Embedded Flow (Deprecated) [#3-embedded-flow-deprecated]

The previous method of loading the auth\_url inside an iframe and handling postMessage events manually is no longer recommended. If you are currently using this approach, migrate to the [Link SDK](https://github.com/Fiskil/link) for a simpler and more reliable integration.

For reference, the legacy embedded flow documentation remains available [here](/data-api/guides/core-concepts/auth-sessions/embedded).

Restricting to a Specific Institution [#restricting-to-a-specific-institution]

You can skip the institution selection step by providing an institution\_id when creating the Auth Session:

```json
{
  "institution_id": "88888",
  "redirect_uri": "https://yourapp.com/redirect",
  "cancel_uri": "https://yourapp.com/cancel"
}
```

When set, users will be sent directly to the specified institution's login screen.


---

# Consents (/data-api/guides/core-concepts/consents)

Understanding how data sharing consent works in Fiskil



Before you can access a user's data that user must consent to data sharing. Consents are started by creating an [Auth Session](/data-api/guides/core-concepts/auth-sessions). After creating the Auth Session, direct your user to the returned `auth_url` where they will sign in to the institution, select accounts to share from, and approve sharing of the data being requested.

After the data sharing has been approved, the user will be redirected back to your application. You will also receive a [Webhook](/data-api/guides/core-concepts/webhooks) with the `end_user_id` and `consent_id`.

<Callout type="info">
  Tip: You can also use the [Consents API](/data-api/api-reference/consents#list-consents) to check if an End User has any active consents.
</Callout>

Ending of Consent [#ending-of-consent]

Consents can be ended in multiple ways:

* By the end user through the institution
* By the institution when the sharing duration expires
* By the institution when the user closes all of their accounts
* By you on behalf of the end user, using the [revoke consent endpoint](/data-api/api-reference/consents#revoke-consent)

In all of these instances you will receieve a [Webhook](/data-api/guides/core-concepts/webhooks) to inform you that the consent has ended.


---

# End Users (/data-api/guides/core-concepts/end-users)

Understanding the core user entity in the Fiskil platform



End Users are the core user entity in the Fiskil platform. An end user represents a person who has data they can to share with your application from an [Institution](/data-api/api-reference/institutions). After the end user gives consent, you can use the Fiskil APIs to collect their data. End Users are referenced by their **id**. You will see all Fiskil data APIs accept an `end_user_id` parameter, this identifies the user you want to fetch the data for. Typically you will save this ID and associate it with a user of your application so that you can fetch new data belonging to the user as it becomes available.

Lifecycle [#lifecycle]

Before you can access consumer data for your users you will need to create an End User in the Fiskil platform. You can use the [Add End User](/data-api/api-reference/end-user#add-end-user) API to do this.

```bash
curl --request POST \
  --url https://api.fiskil.com/v1/end-users \
  --header 'Authorization: Bearer {access_token}' \
  --header 'accept: application/json; charset=UTF-8' \
  --header 'content-type: application/json; charset=UTF-8' \
  --data '{
    "email": "john_starmer@gmail.com",
    "name": "John Starmer",
    "phone": "+614123456789"
  }'
```

You will receive a response with the end user ID:

```json
{
  "end_user_id": "83064af3-bb81-4514-a6d4-afba340825cd"
}
```

<Callout type="info">
  Tip: To prevent duplicate End Users being created for the same user of your application, be sure to save the end user ID against your own user identifier for future use.
</Callout>

Once you've created the end user, you can create [Auth Sessions](/data-api/guides/core-concepts/auth-sessions) so the user can link their accounts and consent to data sharing. You can use the same end user for multiple consents, there's no need to create a different End Users for different institutions. You can access the user's data from all consents by passing their end user ID to the Fiskil API.

Deleting End Users [#deleting-end-users]

If you don't want to maintain the relationship between your users and Fiskil End Users, you can [delete the end user](/data-api/api-reference/end-user#delete-end-user) after you're finished accessing their data. This is an optional step as there is no uniqueness requirement for end users. However, it might make it easier to identify End Users in the Fiskil platform if you remove them when you no longer need them.


---

# Overview (/data-api/guides/core-concepts/overview)

API protocols, headers, and resources



Endpoints [#endpoints]

The Base URL for Fiskil's Data APIs is `https://api.fiskil.com/v1`

API protocols and headers [#api-protocols-and-headers]

The Fiskil API uses POST and GET requests to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Fiskil API is served over HTTPS TLS v1.2+ to ensure data privacy; HTTP and HTTPS with TLS versions below 1.2 are not supported.

Requests target a major API version selected by the `X-Fiskil-Version` header or your Console pin — see [API Versioning](/data-api/guides/core-concepts/versioning).

Postman Collection [#postman-collection]

The Postman collection is a convenient tool for exploring Fiskil API endpoints without writing code. The Postman collection provides pre-formatted requests for almost all of Fiskil API endpoints. All you have to do is fill in your API keys and any arguments.

* [Download - Postman Collection](/assets/Data%20API%20Energy%20V2%20Customer%20Collection.postman_collection.json)
* [Download - Postman Environment](/assets/Data%20API%20Energy%20V2%20Customer%20Environment.postman_environment.json)

OpenAPI Specification [#openapi-specification]

The OpenAPI specification provides a detailed description of the Fiskil API, including endpoints, request parameters, and response formats. You can use this specification to generate client libraries or to understand the API structure.

<OpenAPIDownloads />

Server-side code [#server-side-code]

In your server-side code, ensure that:

* All requests are being made successfully. You may find it useful to view your account's logs as you test your integration.
* All API errors are handled properly.


---

# Testing (/data-api/guides/core-concepts/testing)

Test your Fiskil integration with the Sandbox environment



With the Fiskil Sandbox, you can develop and integration test your application in an environment that mirrors production. The sandbox supports unlimited End-Users and consents with realistic data across both Banking and Energy domains.

In the steps below we'll create a new consent using Fiskil Console and then fetch sample data via the API.

Prerequisites [#prerequisites]

You need a [Fiskil Console](https://console.fiskil.com) account. Sign-up is self-serve — no credit card and no sales call — and the sandbox is available as soon as you're in. Sandbox usage is free and unmetered.

If you need to add teammates or change their permissions, [contact support](https://fiskil.atlassian.net/servicedesk/customer/portal/6).

Getting Started [#getting-started]

Step 1: Generate API Key [#step-1-generate-api-key]

If you haven't already, navigate to [API Keys](https://console.fiskil.com/data-api/settings/api-keys) in the console to create a key pair. Note your `client_id` and `client_secret` for authentication.

Step 2: Get an access token [#step-2-get-an-access-token]

Exchange your credentials for an `access token` using the `/v1/token` endpoint.

```bash
curl --location --request POST 'https://api.fiskil.com/v1/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "client_id": "${client_id}",
  "client_secret": "${client_secret}"
}'
```

Step 3: Create an End-User [#step-3-create-an-end-user]

Create a new End-User to test the APIs. For simplicity, create a single consent per End-User. You'll need a `name`, `email` and `phone`. Use the `access token` from the previous step.

```bash
curl --location --request POST 'https://api.fiskil.com/v1/end-users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${access_token}' \
--data-raw '{
  "name": "Test User",
  "email": "test@example.com",
  "phone": "+1234567890"
}'
```

Step 4: Create Auth Session [#step-4-create-auth-session]

From [End-Users](https://console.fiskil.com/data-api/end-users) in the console, select your user and click **Create Auth Session**. Open the generated link in a new browser window.

Grant access by selecting **Allow**. You'll then see the provider selection screen.

Step 5: Choose the Sandbox Provider [#step-5-choose-the-sandbox-provider]

Select the relevant sandbox provider (Bank or Energy Retailer).

Step 6: Complete OTP Authentication [#step-6-complete-otp-authentication]

Enter any email you can access and click **get code** to receive a one-time password.

Step 7: Account Selection [#step-7-account-selection]

Choose one of the available accounts for your consent. After selecting the account, confirm the consent by clicking **Confirm and share**. You have successfully created a consent in the sandbox environment.

For example account details, see the sub‑pages below for Banking and Energy sample accounts.


---

# API Versioning (/data-api/guides/core-concepts/versioning)

How Fiskil Data API versions work, how to select one, and how upgrades happen



Fiskil's Data API uses major-version numbering. Clients select a single major version — `v1`, `v2`, or `v3` — per request. Inside a major version, Fiskil ships non-breaking changes (new optional fields, new enum values, new endpoints, and bug fixes) automatically and without requiring any client update.

Breaking changes are never shipped inside a major version. They only appear in a new major version that you opt into on your own schedule.

<Callout type="info" title="Live major versions">
  `v1`, `v2`, and `v3` are all live. `v3` is the current major version for new
  accounts. `v1` and `v2` are maintained for existing integrations — see
  [Support timeline](#support-timeline) below.
</Callout>

Selecting a version [#selecting-a-version]

There are two places a version gets chosen. The per-request header always wins.

Per-request: X-Fiskil-Version header [#per-request-x-fiskil-version-header]

Send the header on any request to override your team's Console default for that call:

```bash
curl https://api.fiskil.com/v1/banking/accounts \
  -H 'X-Fiskil-Version: v2' \
  -H 'Authorization: Bearer {token}'
```

Use `v1`, `v2`, or `v3` exactly — the literal major label. Do **not** send full semantic versions like `1.0.0` or `3.0.0`; those will not be accepted.

Team default: Console pinned version [#team-default-console-pinned-version]

Every team has a pinned version in Console. Requests without `X-Fiskil-Version` use this pin. New accounts are pinned to the latest live major version at sign-up.

<Callout type="warning" title="Console upgrades are one-way">
  Moving your Console pin from `v1` to `v2` cannot be reversed in settings.
  Always validate `v2` in production with the `X-Fiskil-Version: v2` header
  first, then flip the pin.
</Callout>

<Callout type="info" title="The /v1/ in the URL is not the API version">
  Every request path starts with `/v1/` as a URL namespace. The API version is
  selected by the `X-Fiskil-Version` header or your Console pin, never by the
  URL segment.
</Callout>

What counts as a breaking change [#what-counts-as-a-breaking-change]

A change is **breaking** (new major version only) if it could cause correctly written client code to fail. Anything else is **non-breaking** and ships inside the current major version.

| Change                                                       | Classification |
| ------------------------------------------------------------ | -------------- |
| Removing a response field                                    | Breaking       |
| Changing the type of a response field (e.g. number → string) | Breaking       |
| Replacing a nested object with an array (or vice versa)      | Breaking       |
| Adding a required request parameter                          | Breaking       |
| Removing or renaming an endpoint                             | Breaking       |
| Adding a new optional request parameter                      | Non-breaking   |
| Adding a new response field                                  | Non-breaking   |
| Adding a new value to a response enum                        | Non-breaking   |
| Adding a new endpoint                                        | Non-breaking   |
| Bug fixes that align behaviour with documented contract      | Non-breaking   |

Parse responses defensively: treat unknown fields as safe to ignore and unknown enum values as valid. That lets non-breaking additions reach your integration without code changes.

Version switcher in the docs [#version-switcher-in-the-docs]

The version switcher in the top navigation changes which major version's API reference you see in these docs. It affects documentation only — it does not send anything to `api.fiskil.com` and does not change your team's runtime behaviour. Runtime behaviour is controlled by the `X-Fiskil-Version` header and your Console pin.

Upgrading to a new major version [#upgrading-to-a-new-major-version]

The same workflow applies to any future major version. It minimises blast radius by keeping production on the old version while you validate the new one.

<Steps>
  <Step title="Pin production to your current version">
    Add `X-Fiskil-Version: v1` to every production request. This freezes your
    current response shape so a later Console change can't surprise you.
  </Step>

  <Step title="Read the upgrade guide">
    Each major release has a dedicated migration doc listing every breaking
    change. For `v2` → `v3` (or `v1` → `v3`), see the
    [Upgrade to v3](/data-api/changelog/upgrade-guide-v3) guide. For `v1` → `v2`,
    see the [Upgrade to v2](/data-api/changelog/upgrade-guide) guide.
  </Step>

  <Step title="Test the new version in production with the header">
    Send `X-Fiskil-Version: v3` on a subset of real production traffic and verify
    the affected endpoints and downstream parsers before committing.
  </Step>

  <Step title="Flip the Console pin">
    Once you've validated `v3` end-to-end, update your team's pinned version in
    Console. You can now drop the explicit header if you want — requests default
    to the pin.
  </Step>
</Steps>

Support timeline [#support-timeline]

Each major version is supported for at least **12 months** from release. When a major version is scheduled for deprecation, the timeline is announced in the [Changelog](/data-api/changelog) with enough notice to upgrade.

Non-breaking updates inside a live major version are announced in the changelog but require no action.

Related [#related]

* [Changelog](/data-api/changelog) — release notes for each major version.
* [Upgrade to v3](/data-api/changelog/upgrade-guide-v3) — concrete migration from `v2` (or `v1`) to `v3`.
* [Upgrade to v2](/data-api/changelog/upgrade-guide) — concrete migration from `v1` to `v2`.
* [API Reference](/data-api/api-reference) — per-endpoint shapes. Use the top-nav version switcher to compare `v1`, `v2`, and `v3`.


---

# Webhooks (/data-api/guides/core-concepts/webhooks)

Receive real-time updates from Fiskil directly to your application



Introduction [#introduction]

Webhooks are a powerful way to receive real-time updates from Fiskil directly to your application. Rather than constantly polling Fiskil's API, webhooks allow Fiskil to push notifications to your app whenever specific events occur. This not only optimises performance but also ensures that your app reacts immediately to critical updates like new user consents or fresh banking transactions.

Fiskil sends these notifications over HTTPS in a structured JSON format, making it easy to integrate and automate responses in your backend systems. Whether you're handling financial transactions, energy data, or user consents, webhooks streamline your workflows with up-to-the-minute accuracy.

Why Use Webhooks? [#why-use-webhooks]

* **Real-Time Updates**: Get notified instantly when important events occur, reducing the need for frequent API polling.
* **Automated Workflows**: Trigger backend processes like updating account balances or alerting users as soon as new data is available.
* **Resource Efficient**: Save bandwidth and server resources by receiving data only when it changes.

Common Use Cases [#common-use-cases]

* **User Consent Notifications**: Receive alerts when an end user consents to share their data (`consent.received`), enabling immediate onboarding or data access.
* **Transaction Updates**: Get notified when new transactions are available (`banking.transactions.sync.completed`), allowing your app to update balances or generate spending reports.
* **Energy Data Syncs**: Automatically update your system with the latest energy usage or billing data, keeping your dashboards current.

Webhook Setup [#webhook-setup]

Step 1: Create Your Webhook Endpoint [#step-1-create-your-webhook-endpoint]

Before Fiskil can send you notifications, you need to set up an endpoint to receive them. Here's how:

Create an HTTP/HTTPS Endpoint: [#create-an-httphttps-endpoint]

* Build a URL on your server that can accept POST requests.
* Ensure this endpoint is publicly accessible.
* For production, HTTPS is mandatory to secure data in transit.

Handle Incoming JSON Payloads: [#handle-incoming-json-payloads]

* Your endpoint should parse and handle JSON payloads. The payload structure is documented [below](#payload-format).
* Additionally, to ensure the authenticity of the incoming request, the endpoint should validate it using the secret key provided during webhook registration. See details [below](#verifying-webhook-signatures).
* Use the event data to trigger actions within your application.

Step 2: Register Your Webhook in Fiskil [#step-2-register-your-webhook-in-fiskil]

Access the Fiskil Console: [#access-the-fiskil-console]

* Log in with an account that has Owner or Developer access.

Navigate to Webhooks: [#navigate-to-webhooks]

* Go to [Settings > Webhooks](https://console.fiskil.com).

Register Your Endpoint: [#register-your-endpoint]

* Enter your endpoint URL.
* Select the events you want to subscribe to (e.g., `banking.transactions.sync.completed`).
* Note: You can modify the endpoint URL later, but event subscriptions cannot be changed once created.

Save Your Webhook: [#save-your-webhook]

* After registration, Fiskil will start sending events to your endpoint as they occur.

Step 2: Allowlist the webhook source IP (optional) [#step-2-allowlist-the-webhook-source-ip-optional]

If you use a firewall make sure you add the Fiskil webhook IP addresses to the allowed IPs:

* `35.244.81.128`
* `34.40.183.9`
* `35.197.175.34`
* `34.87.253.122`

Event Types [#event-types]

Consent Events [#consent-events]

* `consent.received`: Triggered when an end user grants data-sharing consent.
* `consent.updated`: Triggered when an end user modifies their consent.
* `consent.revoked`: Triggered when consent expires or is revoked.

Identity Sync Events [#identity-sync-events]

* `common.identity.sync.completed`: Indicates successful syncing of an end user's identity data.

Customer Data Sync Events [#customer-data-sync-events]

Triggered when end-user data is cached or updated in Fiskil's platform.

Energy Industry [#energy-industry]

* `energy.billing.sync.completed`: Billing data synced.
* `energy.usage.sync.completed`: Usage data synced.
* `energy.servicepoints.sync.completed`: Service point data synced.
* `energy.accounts.sync.completed`: Account data synced.
* `energy.concessions.sync.completed`: Concession data synced.
* `energy.der.sync.completed`: Distributed Energy Resource data synced.
* `energy.invoices.sync.completed`: Invoices synced.
* `energy.paymentschedules.sync.completed`: Payment schedules synced.
* `energy.plans.sync.completed`: Energy plans synced.

Banking Industry [#banking-industry]

* `banking.accounts.sync.completed`: Banking account data synced.
* `banking.balances.sync.completed`: Balance data synced.
* `banking.transactions.basic.sync.completed`: Basic transaction data synced.
* `banking.transactions.sync.completed`: Detailed transactions synced (including metadata).
* `banking.transactions.sync.failed`: The transaction refresh job has failed (only for manual triggers).
* `banking.payees.sync.completed`: Payees synced.
* `banking.directdebits.sync.completed`: Direct debits synced.
* `banking.scheduledpayments.sync.completed`: Scheduled payments synced.
* `banking.products.sync.completed`: Banking product data synced.

During the first-time data sync, the following webhook is also triggered once the recent transactions (approximately last 90 days) are available, before the full historical sync completes.

* `banking.transactions.recent.sync.completed`: Recent basic transaction data synced.

Delivery & Payload Structure [#delivery--payload-structure]

Payload Format [#payload-format]

Fiskil delivers webhook payloads in JSON format with the following structure. However, please note that some events may include additional fields specific to the event type, not listed below.

```json
{
  "delivery_attempt": 1,
  "publish_time": "2023-11-24T05:10:03.957Z",
  "message_id": "9061924608716421",
  "data": {
    "consent_id": "1a460c22-c3ca-4901-8269-0b65c155b483",
    "client_id": "2XbIEYCqr3rBLrjPNGmxuB5rqwy",
    "end_user_id": "2XpN1YbKmoFcqbcN1Ji58kWyv3e",
    "event": "energy.accounts.sync.completed",
    "institution_id": "1",
    "account_ids": ["262c6cc1-1b35-4f3f-b3d0-98976a86c6ee"]
  }
}
```

Payload Fields [#payload-fields]

* `delivery_attempt`: Number of retry attempts made to deliver the event (1-5).
* `publish_time`: Timestamp of the event (RFC3339 format).
* `message_id`: Unique identifier for the event (useful for deduplication).
* `data`: Contains event-specific data, including:
  * `event`: Type of event triggered.
  * `end_user_id`: Unique ID of the end user.
  * `client_id`: Your app's unique identifier.
  * `institution_id`: The data holder's ID.
  * `consent_id`: The ID of the user's consent.
  * `refresh_id`: The ID of manually triggered refresh jobs.
  * `account_ids`: the list of accounts related to synced data. It is only available for:
    * `*.accounts.sync.completed`,
    * `*.balances.sync.completed`,
    * `banking.transactions.sync.completed`,
    * `banking.transactions.basic.sync.completed` and
    * `banking.transactions.recent.sync.completed` events.
  * `payee_ids`: the list of payees related to synced data. It is only available for `banking.payees.sync.completed` event.

Retry Logic [#retry-logic]

If Fiskil cannot deliver an event (e.g., server unreachable or non-2xx response), it retries up to 5 times with backoff intervals between 1 to 10 minutes. After exhausting retries, the event is discarded.

Security [#security]

HTTPS Enforcement [#https-enforcement]

For secure data transmission, Fiskil enforces HTTPS on all webhook endpoints in production.

Verifying Webhook Signatures [#verifying-webhook-signatures]

Fiskil includes an HMAC SHA256 signature in the X-Fiskil-Signature header. This ensures that the event comes from Fiskil and hasn't been tampered with.

Verifying Signatures in Go [#verifying-signatures-in-go]

Here's how to verify the signature using Go:

```go
package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/base64"
  "fmt"
)

func main() {
  var payloadData = `{"publish_time":"2023-11-23T03:03:30.792Z","message_id":"9790112556309026","data":{"consent_id":"4a726862-6b39-4cd5-92c0-3d20fe96a202","client_id":"2XbIYazvJeBwaJx1xCaFar64uVk","end_user_id":"2YPr9YiWLNj3KZt9ycjbvy4bRx5","institution_id":"1"}}`
  var signingSecret = "jf+cnWPind3y0kYqJM4cPAC/8kNcwVXE8/fKs/Kz/SxXIkhVfvV8yh8dtEX9+K2PsmItKu5Jqqwy7cw2JQ+ozsSo2M9qmwpPxRMCREO+"
  secretBytes, err := base64.StdEncoding.DecodeString(signingSecret)
  if err != nil {
    panic(err)
  }
  hmac := hmac.New(sha256.New, secretBytes)
  hmac.Write([]byte(payloadData))
  signature := base64.StdEncoding.EncodeToString(hmac.Sum(nil))
  fmt.Println(signature) // Compare this with X-Fiskil-Signature header
}
```

Verifying with OpenSSL [#verifying-with-openssl]

```bash
# Base64 decode the signing secret
$ echo 'jf+cnWPind3y0kYqJM4cPAC/8kNcwVXE8/fKs/Kz/SxXIkhVfvV8yh8dtEX9+K2PsmItKu5Jqqwy7cw2JQ+ozsSo2M9qmwpPxRMCREO+' | base64 -d > secret.key

# Generate the HMAC signature
$ cat data.json | tr -d '\n ' | openssl dgst -sha256 -mac HMAC -macopt key:secret.key

# Compare the output to the X-Fiskil-Signature header value
```

By verifying signatures, you ensure that only legitimate events from Fiskil are processed by your application.

Conclusion [#conclusion]

With Fiskil webhooks, you can build responsive, data-driven applications that react to real-time financial and energy data. By following this guide, you'll be able to securely set up, manage, and verify webhooks to streamline your workflows and deliver timely updates to your users.

For additional help or troubleshooting, refer to our API documentation or contact support.


---

# Authentication (/data-api/guides/getting-started/authentication)

Learn how to authenticate with the Fiskil API



To access the Fiskil API, all requests must be authenticated using a bearer token. This token is obtained by exchanging your API credentials (`client_id` and `client_secret`) via the `/v1/token` endpoint.

Generate API Credentials [#generate-api-credentials]

First, log in to the [Fiskil Console](https://console.fiskil.com) and navigate to **[Settings > API Keys](https://console.fiskil.com/data-api/settings/api-keys)**.

From there, you can generate your `client_id` and `client_secret`. These values are sensitive and should be stored securely.

> Note: You will not be able to view your `client_secret` again after creation.

Obtain an Access Token [#obtain-an-access-token]

Make a `POST` request to the `/v1/token` endpoint with your credentials:

Request [#request]

```bash
curl --request POST https://api.fiskil.com/v1/token \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}'
```

Response [#response]

```json
{
  "token": "your_token",
  "token_type": "Bearer",
  "expires_in": 900
}
```

Use the Access Token [#use-the-access-token]

Include the `token` in the `Authorization` header for all subsequent API requests:

```bash
curl --request GET https://api.fiskil.com/v1/end-users \
--header "Authorization: Bearer your_token"
```

Token Expiry [#token-expiry]

Tokens are valid for 15 minutes (`expires_in: 900`). When your token expires, repeat the token request process to obtain a new one.

Fiskil does not support refresh tokens. Always handle token expiry on the server and regenerate securely when required.

Best Practices [#best-practices]

* Store your `client_secret` securely; do not expose it in frontend code or logs.
* Only use server-side environments to request access tokens.
* Use HTTPS for all requests to the Fiskil API.
* Monitor for `401` responses and implement automatic token renewal on expiry.

For more integration tips, see our [Quickstart guide](/data-api/guides/getting-started/quick-start) and [Go Live Checklist](/data-api/guides/resources/go-live-checklist).


---

# Quick Start (/data-api/guides/getting-started/quick-start)

Get up and running with Fiskil quickly



Welcome to Fiskil! This guide will help you get up and running with your Fiskil integration in no time. Whether you're building a banking or energy application, follow these steps to connect your users' accounts and start pulling data.

1. Create Your Fiskil Account [#1-create-your-fiskil-account]

Start by creating an account through the [Fiskil Console](https://console.fiskil.com). Once registered, you can generate your API keys and access the tools needed to integrate Fiskil into your app or website.

2. Authenticate with Fiskil [#2-authenticate-with-fiskil]

Fiskil authenticates your API requests using API keys generated from the console. Here's how to exchange your API keys for an access token:

Generate API Keys [#generate-api-keys]

In the [Settings > API Keys](https://console.fiskil.com/data-api/settings/api-keys) menu, create an API key, selecting all scopes.

<Callout type="warn">
  Security Note: Save your client ID and client secret, you won't be able to see them again after this!
</Callout>

Request an Access Token [#request-an-access-token]

Make a POST request to the `/v1/token` endpoint. Replace `your_client_id` and `your_client_secret` with the client ID and secret you saved in the previous step.

```bash
curl --location --request POST 'https://api.fiskil.com/v1/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}'
```

<Callout type="info">
  Tip: Check out the full API Reference for code snippets in various programming languages.
</Callout>

<Callout type="warn">
  Security Note: Store the returned `token` securely. All integrations must be handled on the server-side to protect sensitive data.
</Callout>

3. Create an End User [#3-create-an-end-user]

An End User represents a user of your app. You need to create this object to link accounts and manage consent.

Create an End User [#create-an-end-user]

Make a POST request to `/v1/end-users` with the user's details. Replace `your_token` with the token you got from the `/v1/token` endpoint.

```bash
curl --request POST \
  --url https://api.fiskil.com/v1/end-users \
  --header 'Authorization: Bearer your_token' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "user@example.com",
    "name": "User Name",
    "phone": "+1234567890"
  }'
```

Store the `end_user_id` returned in the response for future API calls.

<Callout type="info">
  Tip: Retrieve an existing `end_user_id` using the GET `/end-users` endpoint if needed.
</Callout>

4. Set Up Your Consent Flow [#4-set-up-your-consent-flow]

Fiskil's APIs are use case agnostic, but it's crucial to ensure your users understand what data they're consenting to share.

Customize Consent in the Console [#customize-consent-in-the-console]

Navigate to the [Customize UI](https://console.fiskil.com/data-api/customize-ui) page in the Fiskil Console.

Update:

* **Consent Period**: Choose an appropriate duration
* **Data History**: Limit history to what's necessary for faster sync
* **Use Cases**: Clearly describe why you need access
* **Branding**: Add your logo, company name, and adjust colors to match your brand

Hit "Save" once you're happy with your consent UI.

<Callout type="info">
  Note: To gain production access, you must only collect data essential for your product or service.
</Callout>

5. Create an Auth Session [#5-create-an-auth-session]

An Auth Session facilitates linking a user's account through the consent flow you designed. The Auth Session is used together with the Fiskil Link SDK to embed the account linking interface inside your application.

Create an Auth Session [#create-an-auth-session]

Make a POST request to `/v1/auth/session`:

```bash
curl --request POST \
  --url https://api.fiskil.com/v1/auth/session \
  --header 'Authorization: Bearer ${token}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "cancel_uri": "https://yourapp.com/cancel",
    "end_user_id": "${end_user_id}"
  }'
```

Handle the Response [#handle-the-response]

```json
{
  "auth_url": "https://auth.fiskil.com/?sess_id=your_session_id",
  "expires_at": "2025-12-31T23:59:59Z",
  "session_id": "your_session_id"
}
```

Use the `auth_session_id` with the Fiskil Link SDK to launch the embedded account linking interface in your application.

Using the Link SDK [#using-the-link-sdk]

```bash
npm install @fiskil/link
# or
yarn add @fiskil/link
```

```javascript
import { link } from '@fiskil/link';

const flow = link('auth_session_id');

try {
  const result = await flow;
  console.log('Consent ID:', result.consentID);
} catch (err) {
  console.error('Link error:', err);
}

// Cancel programmatically if needed

// flow.close();
```

For full details on configuration options and error handling, see [Integrating the Link SDK](/data-api/guides/link-widget/integrating-the-link-sdk).

6. Listen for Webhook Events [#6-listen-for-webhook-events]

Once a user completes the consent flow, Fiskil emits webhook events to notify you when data is ready. Listening for these is the recommended integration pattern.

Key events to handle:

* `consent.received` – triggered when the user completes the consent flow
* `banking.transactions.sync.completed` – banking data is synced
* `energy.usage.sync.completed` – energy data is synced

You can register your webhook endpoint in the Fiskil Console under **[Settings > Webhooks](https://console.fiskil.com)**.

Fiskil signs each payload with an HMAC-SHA256 signature in the `X-Fiskil-Signature` header. Make sure to verify this signature before processing.

[Learn more in the Webhooks Guide](/data-api/guides/core-concepts/webhooks)

7. Pull Data Using Fiskil APIs [#7-pull-data-using-fiskil-apis]

Once the user has completed the consent flow, you can access their data using Fiskil's Banking or Energy APIs.

Banking APIs [#banking-apis]

| Endpoint                                                            | Description                                              |
| ------------------------------------------------------------------- | -------------------------------------------------------- |
| [Identity API](/data-api/api-reference/identity)                    | Retrieve identity information of connected bank accounts |
| [Account API](/data-api/api-reference/accounts)                     | Get account details of connected bank accounts           |
| [Balance API](/data-api/api-reference/balance)                      | Access balance data of connected bank accounts           |
| [Transaction API](/data-api/api-reference/getBankingTransactions)   | Fetch transaction history of connected bank accounts     |
| [Payee API](/data-api/api-reference/payee)                          | Get payee details linked to connected bank accounts      |
| [Direct Debit API](/data-api/api-reference/direct-debits)           | View direct debits from connected bank accounts          |
| [Scheduled Payment API](/data-api/api-reference/scheduled-payments) | List scheduled payments from connected bank accounts     |

Energy APIs [#energy-apis]

| Endpoint                                                          | Description                                                  |
| ----------------------------------------------------------------- | ------------------------------------------------------------ |
| [Identity API](/data-api/api-reference/identity)                  | Retrieve identity information of connected energy accounts   |
| [Account API](/data-api/api-reference/energy-accounts)            | Get account details of connected energy accounts             |
| [Balance API](/data-api/api-reference/energy-balances)            | Access balance data of connected energy accounts             |
| [Concession API](/data-api/api-reference/concessions)             | View concessions applied to connected energy accounts        |
| [Billing API](/data-api/api-reference/billing)                    | Retrieve billing information from connected energy accounts  |
| [Invoice API](/data-api/api-reference/invoices)                   | Get invoice data for connected energy accounts               |
| [Usage API](/data-api/api-reference/usage)                        | Access usage and interval data for connected energy accounts |
| [Servicepoint API](/data-api/api-reference/service-points)        | Retrieve site information for connected energy accounts      |
| [DER API](/data-api/api-reference/der)                            | Obtain Distributed Energy Resources (DER) data               |
| [Scheduled Payment API](/data-api/api-reference/payment-schedule) | List scheduled payments from connected energy accounts       |

Note: Most endpoints support retries and idempotency. We recommend listening to webhook events before attempting to fetch data to ensure it's available.

8. Test Your Integration [#8-test-your-integration]

Before moving to production, validate your integration end-to-end:

* Create a test end user
* Run through the consent flow
* Confirm webhook delivery
* Fetch data using the relevant API

Once you're confident in your flow, review our [Launch Checklist](/data-api/guides/resources/go-live-checklist) to prepare for production.

Need Help? [#need-help]

Not a developer? No worries! Reach out to [Fiskil's certified experts](https://www.fiskil.com/contact) or explore our [Open Source examples](https://github.com/fiskil).

🎉 That's it! You're now set up with Fiskil. Let us know what you're building—we'd love to help you out or even feature your product on our blog.


---

# Start Exploring (/data-api/guides/getting-started/start-exploring)

Essential information to kick off with Fiskil



This page summarizes all the essentials you will need to know to kick off with Fiskil. Here you can find best practices and tips to set up your branding, integrate Fiskil and ingest data ASAP.

Create an account and start exploring Fiskil [#create-an-account-and-start-exploring-fiskil]

Contact the Fiskil team to get your account created, if you already have an account go ahead and login to the Console.

Create your API Keys [#create-your-api-keys]

In the Console you can generate new API keys, these credentials are required to access the platforms APIs. Creating a key can be found under **[Settings > API Keys](https://console.fiskil.com/data-api/settings/api-keys)**.

<Callout type="info">
  Tip: Be specific with your key naming and rotate the keys with each major
  product update, or after 90 days.
</Callout>

End Users [#end-users]

The End User entity within Fiskil represents your users, these can be consumers or businesses. The object is used for linking accounts held at institutions and compliance purposes - [Create an end user](/data-api/guides/getting-started/quick-start#3-create-an-end-user)

<Callout type="info">
  Tip: End Users are typically created when the user signs up to your
  application, or when you capture the users email.
</Callout>

Build your consent flow [#build-your-consent-flow]

Build and design a consent flow to connect your users data to your product. The flow is built for any use case and brand, allowing you to control the experience end-to-end.

Pull in data and start delivering new customer experiences Start pulling in data through our [Banking API](/data-api/api-reference) or our [Energy API](/data-api/api-reference).


---

# Banking - Business Accounts (/data-api/guides/help-center/business-accounts)

Guidance and resources for sharing data from business banking accounts.



Sharing data from Business Accounts [#sharing-data-from-business-accounts]

Under the Consumer Data Right (CDR) Open Banking, some banks require businesses and other non-individual account holders (e.g., trusts) to appoint a Nominated Representative before they can share data.

A Nominated Representative (also known as a delegate) is an individual within an organisation who is authorised to manage and share CDR data on its behalf. The process for appointing a Nominated Representative varies by bank - some offer online registration, others provide in-app options, and some require a paper or digital form submission.

Business bank accounts can have a variety of users such as payroll, staff and administrators. To share data via Open Banking you will need to grant specific users the access privileges to share data on behalf of the business. Once this is set up any user with the appropriate privileges can share access to your businesses data with any accredited third party application. This section provides a list of available guides on how to set up business sharing with each respective institution.

[Open Banking Help for Internet Banking for Business](https://www.anz.com.au/privacy/centre/open-banking-data-sharing/internet-banking-for-business-help/), [ANZ IB4B User guide](https://www.anz.com.au/content/dam/anzcomau/documents/pdf/internet-banking-business-customer-user-guide.pdf), [ANZ IB4B Support](https://www.anz.com.au/ways-to-bank/internet-banking/business/support/)

| Bank    | Resources                                                                                                                                                  | CDR Policy Link                                                                                             | CDR Support Email                                                     | CDR Provider Number |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------- |
| CBA     | [Set up a data sharing delegate with NetBank or CommBiz](https://www.commbank.com.au/banking/open-banking/data-sharing-delegate.html)                      | [CBA CDR Policy](https://www.commbank.com.au/CDRpolicy)                                                     | [CBAOpenBanking@cba.com.au](mailto:CBAOpenBanking@cba.com.au)         | DHBNK000007         |
| ANZ     | [Open Banking Help for Internet Banking for Business](https://www.anz.com.au/privacy/centre/open-banking-data-sharing/internet-banking-for-business-help/) | [ANZ CDR Policy](https://www.anz.com/plus/cdrpolicy)                                                        | [openbanking@anz.com](mailto:openbanking@anz.com)                     | DHBNK000005         |
| NAB     | [How to share data using Open Banking](https://www.nab.com.au/customer-notices/open-banking)                                                               | [NAB CDR Policy](https://www.nab.com.au/common/privacy-policy/consumer-data-right-policy)                   | [open.data@nab.com.au](mailto:open.data@nab.com.au)                   | DHBNK000003         |
| Westpac | [How to set up your Business Network for Data Sharing](https://www.westpac.com.au/business-banking/online-banking/support-faqs/data-sharing/)              | [Westpac CDR Policy](https://www.westpac.com.au/business-banking/online-banking/support-faqs/data-sharing/) | [OpenBankingWBC@westpac.com.au](mailto:OpenBankingWBC@westpac.com.au) | DHBNK000001         |

Other Banks with available resources: [#other-banks-with-available-resources]

| Other banks                | Resources                                                                                                   | CDR Policy Link                                                                                                                                | CDR Support Email                                                                           | CDR Provider Number |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------- |
| Suncorp-Metway Limited     | [CDR FAQ](https://suncorp.com.au/banking/help-support/open-banking.html)                                    | [Suncorp CDR Policy](https://www.suncorp.com.au/content/dam/suncorp/bank/documents/personal/help-and-support/open-banking-policy.pdf)          | [OpenBanking@Suncorp.com.au](mailto:OpenBanking@Suncorp.com.au)                             | DHBNK000068         |
| Bank of Queensland Limited | [CDR FAQ](https://www.boq.com.au/personal/banking/openbanking)                                              | [BOQ CDR Policy](https://www.boq.com.au/cdr-policy)                                                                                            | [openbanking.dataholdersupport@boq.com.au](mailto:openbanking.dataholdersupport@boq.com.au) | DHBNK000111         |
| Bankwest Bank              | [CDR FAQ](https://www.bankwest.com.au/help/open-banking)                                                    | [Bankwest CDR Policy](https://www.bankwest.com.au/CDRpolicy)                                                                                   | [CBAOpenBanking@cba.com.au](mailto:CBAOpenBanking@cba.com.au)                               | DHBNK000007         |
| Australian Mutual Bank LTD | [CDR FAQ](https://australianmutual.bank/about-us/open-banking/)                                             | [Australian Mutual Bank LTD CDR Policy](https://australianmutual.bank/reusable-documents/disclosure-documents/consumer-data-right-cdr-policy/) | [info@australianmutual.bank](mailto:info@australianmutual.bank)                             | DHBNK000066         |
| Police Credit Union Ltd    | [CDR FAQ](https://www.policecu.com.au/support/what-is-open-banking-and-how-will-you-benefit-in-the-future/) | [Police Credit Union Ltd CDR Policy](https://www.policecu.com.au/PCUDocuments/Consumer_Data_Right_Policy)                                      | [cdr@policecu.com.au](mailto:cdr@policecu.com.au)                                           | DHBNK000093         |
| Great Southern Bank        | [CDR FAQ](https://www.greatsouthernbank.com.au/open-banking)                                                | [Great Southern Bank CDR Policy](https://www.greatsouthernbank.com.au/tools-and-services/open-banking)                                         | [company.secretary@gsb.com.au](mailto:company.secretary@gsb.com.au)                         | DHBNK000048         |
| ME Bank                    | [CDR FAQ](https://www.mebank.com.au/home/banking-on-the-go/open-banking-me/)                                | [ME Bank CDR Policy](https://www.mebank.com.au/getmedia/61c6f555-e86d-4467-8ced-047518cf724d/CDR-policy)                                       | [openbanking.dataholdersupport@boq.com.au](mailto:openbanking.dataholdersupport@boq.com.au) | DHBNK000111         |
| GMCU                       | [CDR FAQ](https://www.gmcu.com.au/about-us/corporate-information/open-banking/)                             | [GMCU CDR Policy](https://www.gcmutual.bank/tools/banking-services/open-banking/)                                                              | [info@gmcu.com.au](mailto:info@gmcu.com.au)                                                 | DHBNK000126         |
| Bank of Us                 | [CDR FAQ](https://bankofus.com.au/open-banking-3)                                                           | [Bank of Us CDR Policy](https://bankofus.com.au/source-assets/documents/compliance/Consumer-Data-Right-CDR-Policy-20-October-2021.pdf)         | [Projects@Bankofus.com.au](mailto:Projects@Bankofus.com.au)                                 | DHBNK000120         |
| UniBank                    | [CDR FAQ](https://www.unibank.com.au/money-matters/industry-news/open-banking-future-banking-here)          | [UniBank CDR Policy](https://www.unibank.com.au/-/media/global/pdfs/consumer-data-right.ashx)                                                  | [Enquiry@tmbank.com.au](mailto:Enquiry@tmbank.com.au)                                       | DHBNK000073         |


---

# Energy - Business Accounts (/data-api/guides/help-center/energy-accounts)

Guidance and resources for connecting business energy accounts and nominated representatives.



Connecting Energy Business Accounts and Nominating Representatives [#connecting-energy-business-accounts-and-nominating-representatives]

SME and C\&I energy retailer accounts can have a variety of users such as payroll, staff and administrators. To share data you will need to grant specific users the access privileges to share data on behalf of the business.

This is called a Nominated Representative. Once a Nominated Representative is set up, any user with the appropriate privileges can share access to your business's data with any third party application. This guide outlines the processes for adding nominated representatives with major Australian energy providers.

These nomination processes are determined by each energy provider under CDR regulations. Fiskil cannot bypass these requirements, but we're here to support you throughout the process.

Origin Energy [#origin-energy]

Online [#online]

Contact [businesscustomers@originenergy.com.au](mailto:businesscustomers@originenergy.com.au) with:

* Letter of Authority
* Account Number

Small to Medium Businesses [#small-to-medium-businesses]

Call `1300 661 544` to add an authorised representative for CDR.

Large Commercial and Industrial (C&I) Businesses [#large-commercial-and-industrial-ci-businesses]

Call `13 23 34` to add an authorised representative for CDR.

After Setup [#after-setup]

Once added, manage via the online dashboard:

[dashboard.mydata.cdr.originenergy.com.au](https://dashboard.mydata.cdr.originenergy.com.au)

Energy Australia [#energy-australia]

All Business Accounts [#all-business-accounts]

Call `1800 146 749` to nominate a CDR Representative as a contact on the business account.

To Prepare [#to-prepare]

Ensure you have:

* NMI
* ABN
* Account number

After Setup [#after-setup-1]

Identity will be verified via a one-time passcode during first-time setup.

Use EA's online CDR Customer Dashboard (via My Account) to complete the consent and sharing flow, and for ongoing management.

AGL [#agl]

Nominated Representative Requirements [#nominated-representative-requirements]

The nominated person must:

* Have an email registered and authenticated by AGL.
* Be at least 18 years old.

How to Nominate [#how-to-nominate]

The Primary Account Holder must contact your AGL Account Manager or Customer Service to set up an authorised person as a Nominated Representative for CDR.

In some cases, this will first require adding them as an authorised contact.

After Setup [#after-setup-2]

Manage data sharing arrangements for the business via:

* The AGL app
* My Account page
* AGL's CDR dashboard

Add an authorised person to the account via My Account or by contacting AGL directly.

Contact AGL [#contact-agl]

Customer Service: `131 245`

Alinta Energy [#alinta-energy]

Small Business Accounts [#small-business-accounts]

Call `13 39 08`

Large Business Accounts [#large-business-accounts]

Email your request to [ci.services@alintaenergy.com.au](mailto:ci.services@alintaenergy.com.au)

Or contact your dedicated Account Manager.

To Prepare [#to-prepare-1]

Ensure you have:

* Business verification details
* ABN
* Account number

Note: Only the primary account holder can complete this process.

After Setup [#after-setup-3]

Manage consents via Alinta's CDR dashboard (you will receive a one-time passcode for verification).

Momentum Energy [#momentum-energy]

To Nominate a Representative [#to-nominate-a-representative]

Contact your Account Manager directly.

To Prepare [#to-prepare-2]

Ensure you have:

* Representative's full name and contact details
* The NMI/MIRN of the premises
* Account number

Note: For business accounts, use the business checkbox when registering for MyAccount.

Support Contacts [#support-contacts]

Customer Care Phone: `1300 662 778` (weekdays 8 am - 6 pm AEST)

Alternative Customer Care Phone: `1800 794 824` (general CDR inquiries)

Email: [info@momentum.com.au](mailto:info@momentum.com.au)

Ergon Energy [#ergon-energy]

How to Nominate [#how-to-nominate-1]

To add an authorised representative for a business account, complete the "Appointment of authorised representative - business form".

Submit it via:

* Post: Ergon Energy Retail, PO Box 308, Rockhampton QLD 4700
* Email: [enquiry@support.ergonretail.com.au](mailto:enquiry@support.ergonretail.com.au)

Note: Be sure to include your account details and ensure the form is signed by an authorised person within your business.

Alternative Option [#alternative-option]

Call the Business Customer Service Line: `1300 135 210`

Red Energy [#red-energy]

How to Nominate [#how-to-nominate-2]

Only the Company Director or Company Secretary of the business can nominate a representative for CDR data sharing.

Contact Red Energy to appoint a CDR Nominated Representative.

Call `131 806` (Australia) or `+613 9977 6000`.

To Prepare [#to-prepare-3]

Before data sharing can begin, the Nominated Representative individual must be added as an authorised person on the business account. A pre-existing authorisation for an individual to transact on the account does not extend to CDR services.

Ensure the nominated person's full details are ready.

After Setup [#after-setup-4]

Manage consents via Red Energy's CDR Dashboard.

If You're Not Satisfied [#if-youre-not-satisfied]

If you experience difficulty or delays with a provider during the nomination or consent process, you can:

* Raise a complaint with the provider directly - each provider has an internal complaints process.
* If unresolved, escalate the matter to the ACCC at [ACCC-CDR@accc.gov.au](mailto:ACCC-CDR@accc.gov.au) or via the CDR Service Management Portal.
* Lodge a complaint with the Office of the Australian Information Commissioner (OAIC) if the issue relates to privacy or access rights under CDR.

For additional assistance or to discuss your concerns, contact Fiskil Support at [support@fiskil.com](mailto:support@fiskil.com) - we're happy to help guide you through your options.

Energy Retailer Contact Information [#energy-retailer-contact-information]

SME and C\&I energy retailer accounts can have a variety of users such as payroll, staff and administrators. To share data you will need to grant specific users the access privileges to share data on behalf of the business. This is called a Nominated Representative. Once a Nominated Representative is set up any user with the appropriate privileges can share access to your businesses data with any third party application.

List of resources for each energy retailer [#list-of-resources-for-each-energy-retailer]

| Bank                 | Resources | CDR Policy Link                                                                                           | CDR Support Email                                                                                   | CDR Provider Number |
| -------------------- | --------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------- |
| OVO Energy           | CDR FAQ   | [OVO Energy CDR Policy](https://www.ovoenergy.com.au/terms/consumer-data-right-policy)                    | [cdr@ovoenergy.com.au](mailto:cdr@ovoenergy.com.au)                                                 | DH777822            |
| Ergon Energy Retail  | CDR FAQ   | [Ergon Energy Retail CDR Policy](https://www.ergon.com.au/retail/help-and-support)                        | [debra.grieve@energyq.com.au](mailto:debra.grieve@energyq.com.au)                                   | DH777807            |
| Blue NRG             | CDR FAQ   | [Blue NRG CDR Policy](https://www.bluenrg.com.au/wp-content/uploads/2024/05/Blue-NRG-CDR-Policy-2024.pdf) | [compliance@bluenrg.com.au](mailto:compliance@bluenrg.com.au)                                       | DH777829            |
| ENGIE large business | CDR FAQ   | [ENGIE large business CDR Policy](https://engie.com.au/cdr-policy-b2b)                                    | [CDR@help.simplyenergy.com.au](mailto:CDR@help.simplyenergy.com.au)                                 | DH002028            |
| ENGIE                | CDR FAQ   | [ENGIE CDR Policy](https://www.engie.com.au/help-centre/cdr-policy)                                       | [CDR@help.simplyenergy.com.au](mailto:CDR@help.simplyenergy.com.au)                                 | DH002028            |
| 1st Energy           | CDR FAQ   | [1st Energy CDR Policy](https://1stenergy.com.au/wp-content/uploads/2023/10/CDR-Policy.pdf)               | [liam.foden@1stenergy.com.au](mailto:liam.foden@1stenergy.com.au)                                   | DH777810            |
| Red Energy           | CDR FAQ   | [Red Energy CDR Policy](https://www.redenergy.com.au/privacy-policy/consumer-data-right-policy.pdf)       | [consumerdatarightenquiries@redenergy.com.au](mailto:consumerdatarightenquiries@redenergy.com.au)   | DH777827            |
| Lumo Energy          | CDR FAQ   | [Lumo Energy CDR Policy](https://www.lumoenergy.com.au/privacy/consumer-data-right-policy.pdf)            | [consumerdatarightenquiries@lumoenergy.com.au](mailto:consumerdatarightenquiries@lumoenergy.com.au) | DH777826            |
| GloBird Energy       | CDR FAQ   | [GloBird Energy CDR Policy](https://www.globirdenergy.com.au/cdr-policy)                                  | [cs@globirdenergy.com.au](mailto:cs@globirdenergy.com.au)                                           | DH777817            |
| Tango Energy         | CDR FAQ   | [Tango Energy CDR Policy](https://www.tangoenergy.com/consumer-data-right-policy)                         | [support@pacificblue.com.au](mailto:support@pacificblue.com.au)                                     | DH777819            |


---

# Migrating to Fiskil APIs (/data-api/guides/help-center/migrations)

Plan and execute a phased migration to Fiskil with minimal risk and disruption.



Migrating from an existing data provider doesn't have to be a disruptive big-bang deployment. Whether you're moving from custom-built solutions, legacy aggregators, or screen-scraping services, Fiskil supports flexible migration strategies that let you test, learn, and scale at your own pace.

This guide shows you how to design a migration that minimizes risk, maintains user experience, and unlocks the full value of real-time, user-consented data.

Why Choose a Phased Migration? [#why-choose-a-phased-migration]

We recommend a phased rollout. It reduces risk, preserves user experience, and accelerates time-to-value while you adopt Fiskil with confidence.

Risk containment: Issues are isolated to a narrow scope, not your entire user base.

Continuous improvement: Real production feedback guides rapid iteration before broad rollout.

Business continuity: No downtime or disruption to existing flows while you adopt Fiskil.

Progressive enablement: Your team builds expertise as coverage expands.

Migration Strategies [#migration-strategies]

Choose the approach that best aligns with your risk tolerance, technical constraints, and business requirements:

Full Cutover [#full-cutover]

Replace your existing provider completely in a single deployment. This is a viable, clean-slate option - particularly for new applications, pilots, or straightforward integrations - when you're ready to adopt Fiskil end-to-end.

Institution-by-Institution Migration [#institution-by-institution-migration]

Migrate one financial institution at a time. Start with a high-value institution, enable Fiskil for users connecting to that bank while maintaining your existing provider for others, then expand coverage as confidence grows.

Best for: Most production applications where you want to validate data quality and user experience incrementally without disrupting existing flows.

Alternative Approaches [#alternative-approaches]

Parallel Data Collection: Run both providers simultaneously for the same users to compare data quality before switching - useful for mission-critical workloads.

Feature-Based Migration: Move discrete features (e.g., account aggregation, transaction categorization) rather than entire institutions - effective for complex multi-use-case apps.

Planning Your Institution-by-Institution Migration [#planning-your-institution-by-institution-migration]

Before You Start [#before-you-start]

Assess Your Current Integration: Document your existing data flows, user journeys, and business logic dependencies. Understanding these patterns helps you design an equivalent flow with Fiskil while identifying potential challenges early.

Choose Your First Institution: Select a high-value institution with significant user volume but lower business criticality. This gives you meaningful data to validate your integration while minimizing risk.

Set Success Criteria: Define clear metrics for each institution migration including conversion rates, data quality measures, and user satisfaction scores.

Implementation Strategy [#implementation-strategy]

Start small: Begin with a limited cohort for your first institution. Use configuration/feature flags to control routing and enable quick rollbacks.

Observe and optimize: Monitor technical and user experience signals to validate your integration.

Expand scope: Add more institutions and broaden user coverage as confidence grows.

Technical Implementation [#technical-implementation]

Targeting Specific Institutions [#targeting-specific-institutions]

For institution-by-institution migrations, preselect institutions when creating Auth Sessions by passing `institution_id`. This bypasses the institution selection screen and takes users directly to their bank's login interface.

```bash
curl --request POST \
 --url https://api.fiskil.com/v1/auth/session \
 --header 'Authorization: Bearer {access_token}' \
 --header 'Content-Type: application/json' \
 --data '{
 "end_user_id": "eu_12345",
 "institution_id": "10",
 "redirect_uri": "https://yourapp.com/auth/success",
 "cancel_uri": "https://yourapp.com/auth/cancel"
 }'
```

Embedding vs Redirecting [#embedding-vs-redirecting]

When you create an Auth Session, Fiskil returns an `auth_url`. You can either redirect to our hosted consent UI or embed it via iframe to maintain brand continuity - both options deliver a secure, high-conversion experience.

Data Mapping [#data-mapping]

Keep your existing domain models and introduce a translation layer where needed. Fiskil's enrichment and data quality signals can be adopted incrementally without breaking current contracts.

Common Migration Considerations [#common-migration-considerations]

Data schema differences: Add a translation layer where needed; adopt enrichment and quality signals progressively.

User experience: Redirect or embed to fit your UX. Embedded flows typically maximize brand continuity and conversion.

Performance patterns: Enable monitoring/alerting and tune retries, caching, and backoffs as you expand coverage.

Business logic coupling: Isolate provider-specific logic behind clear interfaces to simplify future changes.

Expert Support [#expert-support]

Our team partners with you on strategy and implementation - schema mapping, consent UX, and rollout best practices - so you can migrate with confidence and realize value quickly.

Ready to get started? [Contact our implementation team](mailto:support@fiskil.com) to design a plan tailored to your stack and users.


---

# Banking (/data-api/guides/data-domains/banking)

Fiskil's Banking APIs provide secure, consent-driven access to a customer's financial data, retrieved directly from their connected bank accounts.



Fiskil's Banking APIs provide secure, consent-driven access to a customer's financial data, retrieved directly from their connected bank accounts. This includes account metadata, transaction history, payees, balances, and more.

Once a customer has successfully linked their bank, Fiskil syncs their data and emits webhook events to notify your system when each data type is available.

What Data Can You Access? [#what-data-can-you-access]

| Data Type              | Description                                                            |
| ---------------------- | ---------------------------------------------------------------------- |
| **Identity**           | Verified name, date of birth, contact details, and other personal data |
| **Accounts**           | Account numbers, names, account types, financial institution metadata  |
| **Balances**           | Current and available balances per account                             |
| **Transactions**       | Categorised and enriched transaction history                           |
| **Payees**             | Counterparties associated with outbound transactions                   |
| **Direct Debits**      | Active debit mandates including frequency, status, and linked accounts |
| **Scheduled Payments** | Future-dated outgoing payments scheduled via the institution           |

Refer to the [Banking API Reference](/docs/data-api/api-reference/banking-overview) for full endpoint documentation.

Data Availability and Integration Flow [#data-availability-and-integration-flow]

Once a user has successfully linked a financial institution, Fiskil begins syncing data and emits webhook events as each dataset becomes available.

For example:

* `banking.transactions.sync.completed` → transaction history is ready
* `banking.accounts.sync.completed` → account metadata is available

We recommend using these webhooks to trigger your backend data fetches. Avoid polling.

See the [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks) for integration details.

Example Use Cases [#example-use-cases]

Fiskil's Banking APIs can support a wide range of product experiences. For example:

* **Account verification** -- Retrieve verified account ownership details to support onboarding, direct debit setup, or compliance workflows.
* **Spending insights** -- Analyse transaction history to categorise spending or detect patterns.
* **Balance aggregation** -- Show users a combined financial view across multiple institutions.
* **Recurring payment summaries** -- Identify and summarise recurring debits or subscriptions.
* **Cash flow tracking** -- Calculate inflows and outflows for budgeting or business finance use cases.

Transaction Date Fields [#transaction-date-fields]

Transactions can carry more than one datetime field, and not every field is populated for every transaction. When filtering by date range with the `from`/`to` parameters on [Get Transactions](/data-api/api-reference/getBankingTransactions), Fiskil checks the posted datetime first and falls back to the execution datetime if it's empty — so a transaction that hasn't posted yet (for example, one still pending at the institution) can still fall inside your requested range via its execution datetime.

If your integration reads transaction dates directly (rather than relying solely on the `from`/`to` filter), apply the same fallback: prefer the posted datetime when present, and fall back to the execution datetime when it isn't, rather than assuming a single field is always populated.

Best Practices [#best-practices]

* Always use `end_user_id` as your primary reference when fetching data.
* Use pagination when retrieving transaction history (`page[size]`, `page[before]`, etc.).
* Do not store account or balance data — always retrieve fresh when needed.
* Handle webhook retries idempotently using the `message_id` field in the payload.
* Ensure your webhook endpoints are HTTPS-secured and verified.

Next Steps [#next-steps]

* To understand how users link their accounts, read the [Auth Sessions](/docs/data-api/guides/core-concepts/auth-sessions)
* For a breakdown of user identity data across domains, visit [Identity Data](/docs/data-api/guides/data-domains/identity)
* To explore available API endpoints, see the [Banking API Reference](/docs/data-api/api-reference/banking-overview)


---

# Energy Data (/data-api/guides/data-domains/energy)

Fiskil's Energy APIs allow your application to securely access utility account data authorised by the customer through a linked energy provider.



Fiskil's Energy APIs allow your application to securely access utility account data authorised by the customer through a linked energy provider. This includes usage, billing history, concessions, and service point information.

After a customer has connected their energy institution and consented to data sharing, Fiskil syncs available data and notifies your system via webhook events when it is ready to be accessed.

What Data Can You Access? [#what-data-can-you-access]

| Data Type              | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| **Identity**           | Name, contact details, and verified customer identifiers             |
| **Accounts**           | Account numbers, plan information, status, and institution metadata  |
| **Usage**              | Interval energy usage (e.g. smart meter reads), including timestamps |
| **Billing**            | Billing summaries and historical charges                             |
| **Invoices**           | Structured invoice-level data, including totals and due dates        |
| **Concessions**        | Government rebates or support linked to the account                  |
| **Service Points**     | Physical site data including supply address and NMI                  |
| **DER**                | Distributed Energy Resource data (e.g. rooftop solar, batteries)     |
| **Scheduled Payments** | Upcoming payments scheduled via the institution                      |

Refer to the [Energy API Reference](/docs/data-api/api-reference/energy-overview) for full endpoint specifications.

Data Availability and Integration Flow [#data-availability-and-integration-flow]

After a successful connection, Fiskil initiates data syncs and emits webhook events as data becomes available.

Typical event types include:

* `energy.accounts.sync.completed`
* `energy.usage.sync.completed`
* `energy.billing.sync.completed`

You should listen for these events and only fetch data once syncs are complete. This reduces latency and ensures data accuracy.

See the [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks) for details on payload structure, security, and retry handling.

Example Use Cases [#example-use-cases]

Fiskil's Energy APIs can support a range of use cases for energy retailers, aggregators, and climate-focused applications. For example:

* **Energy usage visualisation** -- Display interval consumption data in user dashboards
* **Automated billing summaries** -- Show recent bills, overdue amounts, and payment schedules
* **DER insights** -- Track solar export or battery performance for connected homes
* **Concession eligibility checks** -- Validate if government rebates are correctly applied
* **Service point lookups** -- Support supply-side diagnostics or location mapping

Best Practices [#best-practices]

* Use `end_user_id` to query for energy data — you do not need to store account or consent identifiers
* Expect variability in usage data granularity depending on the institution (e.g. daily vs. 30-minute intervals)
* Reconnect the user if consent expires or access is revoked (see [Consents](/docs/data-api/guides/core-concepts/consents))
* Use webhooks as your trigger for backend sync and processing — avoid polling

Next Steps [#next-steps]

* Review the [Consents](/docs/data-api/guides/core-concepts/consents) and [End Users](/docs/data-api/guides/core-concepts/end-users) guides to understand how energy accounts are linked
* Explore webhook events in more depth in the [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks)
* See the [Energy API Reference](/docs/data-api/api-reference/energy-overview) for endpoint details


---

# Identity Data (/data-api/guides/data-domains/identity)

Fiskil provides access to verified identity information associated with a user's connected accounts.



Fiskil provides access to verified identity information associated with a user's connected accounts. This data can be retrieved from either banking or energy institutions, depending on the domains your application supports.

The Identity API is useful for onboarding, account verification, compliance, and personalisation workflows.

What Is Available [#what-is-available]

Identity data is retrieved from the user's linked institution after a successful connection and sync.

The fields available may vary slightly between providers, but generally include:

| Field                    | Description                                     |
| ------------------------ | ----------------------------------------------- |
| **Full Name**            | Verified legal name as registered with provider |
| **Phone Number**         | Mobile or contact number                        |
| **Email Address**        | Contact email address                           |
| **Residential Address**  | Postal or supply address                        |
| **Institution Metadata** | Source of identity data (e.g. bank or retailer) |

You can retrieve identity data for all connected institutions or filter by `end_user_id`.

Refer to the [Identity API Reference](/docs/data-api/api-reference/identity) for full details.

When Identity Data Becomes Available [#when-identity-data-becomes-available]

Identity information is accessible only after:

1. The user has linked an institution (see [End Users](/docs/data-api/guides/core-concepts/end-users))
2. Fiskil has completed the identity sync
3. Your system receives the `common.identity.sync.completed` webhook

Always wait for the relevant webhook before attempting to retrieve identity data.

For more on handling events, see the [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks).

Example Use Cases [#example-use-cases]

* **Onboarding verification** -- Confirm user-provided details during sign-up
* **Account ownership checks** -- Match account data with verified identity information
* **Personalisation** -- Pre-fill forms or tailor user experiences
* **Compliance workflows** -- Support identity confirmation for regulated use cases

Best Practices [#best-practices]

* Always use `end_user_id` to retrieve identity data
* Rely on webhooks to determine when identity data is available — avoid polling
* Identity field coverage may vary by institution
* Avoid storing sensitive identity data unless necessary for your application and compliant with regulation

Related Guides [#related-guides]

* [End Users](/docs/data-api/guides/core-concepts/end-users)
* [Consents](/docs/data-api/guides/core-concepts/consents)
* [Identity API Reference](/docs/data-api/api-reference/identity)


---

# Income (/data-api/guides/data-domains/income)

Fiskil's Income API provides structured insights into consumer income using enriched transaction data.



Fiskil's Income API provides structured insights into consumer income. Using enriched transaction data, it identifies salary deposits, recurring income streams, and patterns of inflows to help you power financial decisioning, credit assessments, and affordability checks.

Once a customer has successfully linked their bank and Fiskil has processed their transactions, you can query the `/banking/income` endpoint to retrieve their income profile.

What Data Can You Access? [#what-data-can-you-access]

| Data Type          | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| **Income Sources** | Identified salary or recurring credits into the user's bank accounts |
| **Frequency**      | Detection of `WEEKLY`, `BIWEEKLY`, or `MONTHLY` income patterns      |
| **Amounts**        | Gross income estimates calculated from transaction inflows           |
| **Accounts**       | Accounts receiving identified income streams                         |

Refer to the [Income API Reference](/docs/data-api/api-reference/income) for full endpoint documentation.

Data Availability and Integration Flow [#data-availability-and-integration-flow]

The `/banking/income` endpoint depends on transaction data being available. This means you should only query it after the initial transaction sync has completed.

Integration flow:

1. **Create an end-user and consent** → As shown in the [Quick Start Guide](/docs/data-api/guides/getting-started/quick-start).
2. **Wait for webhook** → Listen for `banking.transactions.basic.sync.completed` (see [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks)).
3. **Fetch income data** → Once the webhook fires, call `/banking/income?end_user_id={{end_user_id}}` to retrieve the user's income profile. Income detection defaults to up to 6 months worth of income data of category `INCOME_SALARY`, see the [Income API Reference](/docs/data-api/api-reference/income) for customisation options. For an up to date list of income related categories, see the [Fiskil Taxonomy](/downloads/categories-taxonomy.csv).

We recommend using webhooks to trigger income data fetches instead of polling.

Example Use Cases [#example-use-cases]

Fiskil's Income API enables a range of financial product experiences:

* **Credit decisioning** -- Assess income stability and regularity for loan approvals.
* **Affordability checks** -- Verify customer income as part of responsible lending requirements.
* **Financial wellness** -- Help users understand their income patterns and stability.
* **Employment verification** -- Detect salary deposits for onboarding or compliance workflows.

Best Practices [#best-practices]

* Always provide `end_user_id` when querying `/banking/income`.
* Do not call `/banking/income` until the `banking.transactions.basic.sync.completed` webhook has been received.
* Ensure your webhook endpoints are HTTPS-secured and validated.

Next Steps [#next-steps]

* Review the [Quick Start Guide](/docs/data-api/guides/getting-started/quick-start) to learn how to create users and consents.
* See the [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks) for listening to transaction sync events.
* Explore the [Income API Reference](/docs/data-api/api-reference/income) for details on available fields and response schema.


---

# Flow Overview (/data-api/guides/link-widget/flow-overview)

Understanding the steps in the Fiskil consent flow



The Fiskil Link widget guides users through a multi-step consent flow. Understanding each step helps you design a better user experience and handle edge cases.

Flow Steps [#flow-steps]

1. Institution Selection [#1-institution-selection]

Users first see a list of available institutions (banks or energy providers) they can connect. The list is filtered based on your account configuration.

2. Authentication [#2-authentication]

After selecting an institution, users authenticate with their existing credentials at that institution. This typically involves:

* Username/password entry
* Multi-factor authentication (SMS, email, or app-based)
* Security questions

3. Account Selection [#3-account-selection]

Once authenticated, users see a list of their accounts at the institution. They select which accounts to share with your application.

4. Consent Confirmation [#4-consent-confirmation]

Users review the data being shared and the consent duration. This screen displays:

* Your company name and logo
* Fiskil's name, identifying it as the accredited party facilitating the connection
* Data types being requested
* Consent period (how long you'll have access)
* Purpose of data access (your configured use cases)

In Australia (CDR), the accredited data recipient facilitating the sharing must be identified to the user, so Fiskil's name appears alongside yours — this can't be configured away.

5. Completion [#5-completion]

After confirming, users are returned to your application with a successful consent. You can now access their data via the Fiskil APIs.

Handling Different Outcomes [#handling-different-outcomes]

Successful Completion [#successful-completion]

The user completed the entire flow. You receive a `consent_id` and can start fetching data.

User Cancellation [#user-cancellation]

The user closed the widget or clicked cancel. No consent was created.

Authentication Failure [#authentication-failure]

The user entered incorrect credentials or failed multi-factor authentication. They can retry or cancel.

Institution Unavailable [#institution-unavailable]

Occasionally an institution may be temporarily unavailable. The user will see an error message and can try again later.

Best Practices [#best-practices]

1. **Prepare Users**: Explain what data you'll access and why before launching the Link widget
2. **Handle All Outcomes**: Implement proper error handling for cancellations and failures
3. **Listen for Webhooks**: Don't rely solely on the client callback—use webhooks for reliable data sync notifications
4. **Test Thoroughly**: Use the sandbox environment to test various scenarios
5. **Explain Fiskil's Role**: Tell users up front that you use Fiskil, an accredited data recipient, to connect their account — users who see this before the flow starts are less likely to raise a support ticket asking who Fiskil is


---

# Introduction (/data-api/guides/link-widget)

Embed Fiskil's consent flow inside your application



The Fiskil Link Widget provides a seamless way to integrate Fiskil's consent flow directly into your application. Instead of redirecting users to an external page, you can embed the entire account linking experience within your app's UI.

Benefits [#benefits]

* **Seamless User Experience**: Keep users within your app during the consent flow
* **Easy Integration**: Single function call to launch the consent UI
* **Customizable**: Matches your branding configured in the Fiskil Console
* **Reliable**: Handles edge cases and errors automatically

How It Works [#how-it-works]

1. Create an [Auth Session](/data-api/guides/core-concepts/auth-sessions) on your server
2. Pass the `auth_session_id` to the Link SDK on the client
3. The SDK renders the consent flow in an overlay
4. Once complete, you receive the `consent_id` in the callback

Quick Example [#quick-example]

```javascript
import { link } from '@fiskil/link';

const flow = link('auth_session_id');

try {
  const result = await flow;
  console.log('Success! Consent ID:', result.consentID);
} catch (err) {
  console.error('Link error:', err);
}
```

Next Steps [#next-steps]

* [Integrating the Link SDK](/data-api/guides/link-widget/integrating-the-link-sdk) - Full integration guide
* [Flow Overview](/data-api/guides/link-widget/flow-overview) - Understand the consent flow steps


---

# Integrating the Link SDK (/data-api/guides/link-widget/integrating-the-link-sdk)

Step-by-step guide to integrate the Fiskil Link SDK



The [Fiskil Link SDK](https://github.com/Fiskil/link) makes it simple to launch the consent flow inside your web application. You provide an `auth_session_id` created on your backend, and the SDK handles the rest — from rendering the consent UI to returning the result of the flow.

<Callout type="info">
  To use this SDK, you'll need a Fiskil team account. If you don't have an account, you can [get in touch](https://www.fiskil.com/contact) for a quick demo. If you're new to the Fiskil platform, start with the [Quick Start Guide](/data-api/guides/getting-started/quick-start).
</Callout>

Integration Flow [#integration-flow]

1) Install Link SDK [#1-install-link-sdk]

This step is only required if you're using Node.js — for browser usage, you can import the SDK directly from CDN.

```bash
npm install @fiskil/link
# or
pnpm add @fiskil/link
```

2) Create an Auth Session [#2-create-an-auth-session]

On your backend, call the [`/v1/auth/session`](/data-api/api-reference/linking-accounts#create-auth-session) endpoint with the end user ID. The `redirect_uri` and `cancel_uri` can be left blank (empty string) but `end_user_id` is required.

```bash
curl --request POST \
  --url https://api.fiskil.com/v1/auth/session \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{"end_user_id": "${end_user_id}"}'
```

3) Launch the SDK [#3-launch-the-sdk]

In your frontend, call the `link()` function with the `auth_session_id` to open the consent flow. On success, the result contains a `consentID` which can be used to fetch user data from the Fiskil APIs, or an error `code` on error.

4) Handle the Result [#4-handle-the-result]

When the flow finishes, the SDK resolves with `{ consentID?, redirectURL? }`.
If the flow fails or the user exits, it rejects with a typed error.

Quick Start (ESM / TypeScript) [#quick-start-esm--typescript]

```typescript
import { link } from '@fiskil/link';

// Start the consent flow
const flow = link('auth_session_id');

try {
  const result = await flow;
  console.log('Consent ID:', result.consentID);
  // Use consentID to fetch data via Fiskil APIs
} catch (err) {
  console.log('Link error code:', (err as any).code);
}

// To cancel the flow programmatically
// flow.close();
```

Quick Start (UMD / CDN) [#quick-start-umd--cdn]

```html
<!-- Include the SDK from the Fiskil CDN -->
<script src="https://cdn.jsdelivr.net/npm/@fiskil/link@0.1.6-beta/dist/fiskil-link.umd.js"></script>
<script>
  // Launch the consent flow with your auth_session_id
  const flow = FiskilLink.link('auth_session_id');

  // Handle the result
  flow
    .then((result) => {
      console.log('Consent complete:', result.consentID);
      // Use consentID to fetch data from Fiskil APIs
    })
    .catch((err) => {
      console.error('Consent failed:', err);
    });

  // You can also close the flow programmatically if needed:
  // flow.close();
</script>
```

API Usage [#api-usage]

link(sessionId, options?) [#linksessionid-options]

Creates and mounts the consent UI. Returns a `LinkFlow` object that is both:

* a **Promise** that resolves to either `LinkResult` or `LinkError` based on the flow result, and
* a **controller** with `.close()` to cancel the flow programmatically

Options [#options]

| Option      | Type     | Description                                                                     |
| ----------- | -------- | ------------------------------------------------------------------------------- |
| `timeoutMs` | `number` | Rejects if no message is received within this time. Default: `600000` (10 min). |

Result [#result]

When the consent flow is completed successfully, the link flow resolves with the `LinkResult` payload, which includes the `consentID` to fetch user data from the Fiskil platform.

```typescript
type LinkResult = {
  consentID?: string;
};
```

* `consentID` — use this to retrieve data from Fiskil APIs

Error Handling [#error-handling]

The promise rejects with a `LinkError` if any error is encountered during the consent flow. For `LINK_INVALID_SESSION`, the iframe remains mounted. You can close it programmatically with `.close()`.

```typescript
interface LinkError extends Error {
  name: 'LinkError';
  code: LinkErrorCode;
  details?: unknown;
}
```

Error Codes [#error-codes]

| Code                                | Description                                    |
| ----------------------------------- | ---------------------------------------------- |
| `LINK_NOT_FOUND`                    | Consent UI container not found in DOM          |
| `LINK_TIMEOUT`                      | Flow exceeded timeout duration                 |
| `LINK_USER_CANCELLED`               | User cancelled or flow closed programmatically |
| `LINK_INVALID_SESSION`              | The provided Auth Session is invalid           |
| `LINK_ORIGIN_MISMATCH`              | Message received from unexpected origin        |
| `LINK_INTERNAL_ERROR`               | An unrecognized internal error occurred        |
| `CONSENT_UPSTREAM_PROCESSING_ERROR` | Institution-level error during consent         |
| `CONSENT_ENDUSER_DENIED`            | User denied consent                            |
| `CONSENT_OTP_FAILURE`               | OTP verification failed                        |
| `CONSENT_ENDUSER_INELIGIBLE`        | User not eligible for data sharing             |
| `CONSENT_TIMEOUT`                   | User abandoned the flow before completing it   |

For troubleshooting guidance, see [Error Types](/data-api/api-reference/errors#error-types).

React Integration Example [#react-integration-example]

```tsx
import { useState } from 'react';
import { link } from '@fiskil/link';

function LinkAccountButton({ authSessionId, onSuccess }) {
  const [loading, setLoading] = useState(false);

  const handleClick = async () => {
    setLoading(true);
    try {
      const result = await link(authSessionId);
      onSuccess(result.consentID);
    } catch (err) {
      console.error('Link failed:', err.code);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleClick} disabled={loading}>
      {loading ? 'Connecting…' : 'Link Account'}
    </button>
  );
}
```

Next Steps [#next-steps]

* Review the [Flow Overview](/data-api/guides/link-widget/flow-overview) to understand the user experience.
* Set up [Webhooks](/data-api/guides/core-concepts/webhooks) to listen for consent events.
* Begin retrieving data through the [Banking API](/data-api/api-reference/banking) or [Energy API](/data-api/api-reference/energy).


---

# Best Practices (/data-api/guides/resources/best-practices)

Recommendations for building robust Fiskil integrations



Follow these best practices to build a reliable, secure, and user-friendly Fiskil integration.

Security [#security]

Protect Your Credentials [#protect-your-credentials]

* Never expose your `client_secret` in frontend code
* Store credentials in environment variables or a secrets manager
* Rotate API keys periodically (every 90 days recommended)

Server-Side Integration [#server-side-integration]

* Make all API calls from your server, not the browser
* Use HTTPS for all communications
* Validate webhook signatures before processing

Handle Tokens Securely [#handle-tokens-securely]

* Don't store access tokens in browser storage
* Implement proper token expiry handling
* Never log tokens or credentials

Data Handling [#data-handling]

Request Only What You Need [#request-only-what-you-need]

* Configure consent to request only essential data scopes
* Shorter consent periods are more user-friendly
* Limit data history to what's necessary

Cache Wisely [#cache-wisely]

* Use webhook events to know when new data is available
* Don't poll APIs excessively
* Implement proper cache invalidation

Handle Data Updates [#handle-data-updates]

* Data can change between syncs
* Implement proper update/upsert logic in your database
* Consider soft deletes for removed records

User Experience [#user-experience]

Clear Communication [#clear-communication]

* Explain what data you're accessing and why
* Be transparent about how data will be used
* Provide easy access to consent management

Error Handling [#error-handling]

* Handle all error cases gracefully
* Provide helpful error messages to users
* Log errors for debugging

Loading States [#loading-states]

* Show progress indicators during the Link flow
* Inform users when data is syncing
* Handle timeouts appropriately

Webhooks [#webhooks]

Reliability [#reliability]

* Always return 2xx status codes promptly
* Process webhook payloads asynchronously
* Implement idempotency using `message_id`

Security [#security-1]

* Verify webhook signatures
* Only accept webhooks from Fiskil IPs
  * `35.244.81.128`
  * `34.40.183.9`
  * `35.197.175.34`
  * `34.87.253.122`
* Use HTTPS endpoints

Error Handling [#error-handling-1]

* Handle retries gracefully
* Log failed webhook processing for investigation
* Monitor webhook delivery health

Testing [#testing]

Use the Sandbox [#use-the-sandbox]

* Test all flows in sandbox before production
* Create multiple test end-users for different scenarios
* Verify webhook delivery in sandbox

Test Edge Cases [#test-edge-cases]

* User cancellation
* Authentication failures
* Network errors
* Token expiry

Monitoring [#monitoring]

Log Important Events [#log-important-events]

* API call successes and failures
* Webhook receipts
* Consent lifecycle events

Set Up Alerts [#set-up-alerts]

* Monitor for elevated error rates
* Track API latency
* Alert on webhook delivery failures


---

# Go Live Checklist (/data-api/guides/resources/go-live-checklist)

Everything you need to complete before launching your Fiskil integration in production



Work through this checklist before launching your Fiskil integration in production. Not every item is strictly required for basic operation, but completing the full list will result in a more robust, secure, and maintainable integration.

Request Live Access [#request-live-access]

Live access is requested and granted entirely through the [Fiskil Console](https://console.fiskil.com/) — there is no separate email or paperwork to complete. Open the [onboarding questionnaire](https://console.fiskil.com/data-api/onboarding-questionnaire) in the Console and complete the steps below to unlock the production environment.

<Callout type="info">
  Once you submit your questionnaire, our team will review it and follow up directly in the Console. You can track the status of your request from the same page.
</Callout>

<Steps>
  <Step title="Complete Your Application and Company Profile">
    Fill in your application and company profile in the [onboarding questionnaire](https://console.fiskil.com/data-api/onboarding-questionnaire). Some institutions require this information before they will grant access.
  </Step>

  <Step title="Submit Your Security Questionnaire">
    Submit your security questionnaire from the same [onboarding flow](https://console.fiskil.com/data-api/onboarding-questionnaire). This is required for live access.
  </Step>

  <Step title="Review the Compliance Checklist">
    Review the [Compliance Checklist](#compliance-checklist) below to ensure your integration meets all mandatory compliance requirements.
  </Step>

  <Step title="Work Through the Developer Checklist">
    Work through the [Developer Checklist](#developer-checklist) below to verify your technical integration is production-ready.
  </Step>

  <Step title="Set Up Your Production Environment">
    Once your access is approved, configure your production environment in the [Fiskil Console](https://console.fiskil.com/) and run a final end-to-end test before going live.
  </Step>
</Steps>

Compliance Checklist [#compliance-checklist]

All items in this checklist are mandatory requirements for production access.

Consent UI Requirements [#consent-ui-requirements]

In the [Fiskil Console](https://console.fiskil.com/), use “Customize UI” to:

* [ ] Customize the UI branding to match your product or brand identity.
* [ ] Configure an appropriate consent period that aligns with your use case. For example, use a one-time consent for single affordability checks, or up to 12 months for ongoing financial monitoring.
* [ ] Clearly document and communicate all intended data usage purposes in your Consent UI.

Data Management Requirements [#data-management-requirements]

Fiskil will provide guidance and support to ensure you establish the following controls:

* [ ] Implement and document your data minimization strategy, ensuring you only store essential data.
* [ ] Establish processes for data deletion or de-identification when no longer needed.
* [ ] Implement testing procedures to verify compliance with data management requirements.
* [ ] Ensure any storage of identifiable customer data complies with local data sovereignty regulations.

Developer Checklist [#developer-checklist]

Verify the following technical requirements before taking your Fiskil integration live.

Error Handling [#error-handling]

Discovering an unhandled error type after launch is painful. Make sure your code is defensive and handles every error case — not just the common ones, but also those you expect to “never” happen.

* [ ] Account for different error types that may be thrown by Fiskil APIs and ensure each edge case is handled.
* [ ] Implement retry logic or error handling for intermittent outages or connectivity errors at supported institutions. Fiskil API calls may occasionally fail due to issues at data holder institutions.

Storage and Logging [#storage-and-logging]

Log Fiskil identifiers and IDs properly to enhance security. When contacting Support about a specific request or webhook, these will be required.

Ensure the following identifiers are securely logged:

| Identifier    | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| `end_user_id` | Included in most requests to identify the end user whose data is being accessed. |
| `consent_id`  | The consent identifier associated with each data sharing consent.                |
| `session_id`  | The session identifier associated with every consent created or attempted.       |
| `error_id`    | Included in all errors returned to uniquely identify the error reported.         |

End User Management [#end-user-management]

* [ ] Delete end users that are no longer using the product or receiving a service from your product.

Product-Specific Recommendation: Transaction API [#product-specific-recommendation-transaction-api]

* [ ] If fetching historical transaction data, make sure your app implements pagination logic.
* [ ] The Transaction API natively supports the categorization of transactions through the `categories` object. For a comprehensive understanding of the classification system, download the [Categories Taxonomy CSV](/downloads/categories-taxonomy.csv), which provides detailed information on all category types, subtypes, and their hierarchical relationships supported by Fiskil.


---

# Mobile Integration (/data-api/guides/resources/mobile-integration)

Integrate the Fiskil consent flow into iOS and Android apps using the Link SDK in a WebView



The Fiskil Link SDK currently provides a **JavaScript client SDK** ([`@fiskil/link`](https://github.com/Fiskil/link)) for web applications. Native Android and iOS SDKs will be available in the coming months.

In the meantime, you can integrate the full consent flow into your mobile app by embedding the Link SDK inside a **WebView**. This is the recommended approach -- it uses the same SDK as a web integration, runs the consent flow in an overlay managed by the SDK, and communicates results back to your native code through a JavaScript bridge.

<Callout type="info">
  This guide assumes you've already set up your backend to [create Auth Sessions](/data-api/guides/core-concepts/auth-sessions) and are familiar with the [Link SDK](/data-api/guides/link-widget/integrating-the-link-sdk). If you're new to the Fiskil platform, start with the [Quick Start Guide](/data-api/guides/getting-started/quick-start).
</Callout>

How It Works [#how-it-works]

1. Your **backend** creates an Auth Session via `POST /v1/auth/session` and returns the `auth_session_id` to the mobile app
2. The mobile app loads a **local HTML page** in a WebView that includes the `@fiskil/link` SDK from CDN
3. The native app passes the `auth_session_id` into the WebView via a JavaScript bridge
4. The Link SDK opens the consent flow overlay inside the WebView
5. When the flow completes (or fails), the SDK resolves and the HTML page sends the result back to native code through the JavaScript bridge

<Mermaid
  chart="sequenceDiagram
    participant App as Mobile App
    participant Backend as Your Backend
    participant WebView as WebView
    participant SDK as Link SDK
    participant Fiskil as Fiskil Auth

    App->>Backend: Request auth session
    Backend->>Fiskil: POST /v1/auth/session
    Fiskil-->>Backend: auth_session_id
    Backend-->>App: auth_session_id
    App->>WebView: Load HTML with Link SDK
    App->>WebView: Pass auth_session_id via JS bridge
    WebView->>SDK: link(auth_session_id)
    SDK->>Fiskil: Open consent flow overlay
    Fiskil-->>SDK: consentID or error
    SDK-->>WebView: Result
    WebView->>App: Send result via JS bridge"
/>

Create the Auth Session [#create-the-auth-session]

On your backend, create an Auth Session. When using the Link SDK, you only need to provide the `end_user_id` -- no `redirect_uri` or `cancel_uri` is required.

```bash
curl --request POST \
  --url https://api.fiskil.com/v1/auth/session \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{"end_user_id": "${end_user_id}"}'
```

The response includes the `session_id` to pass to the Link SDK:

```json
{
  "id": "5qcql2s0bn9qfh1m5qd1sl4gth",
  "session_id": "ea564d-56012s4-6ds4564",
  "auth_url": "https://auth.fiskil.com/consent?session=ea564d-56012s4-6ds4564",
  "expires_at": 1621083785
}
```

The Bridge HTML Page [#the-bridge-html-page]

Create a lightweight HTML page that loads the Link SDK from CDN and communicates with your native app through a JavaScript bridge. Bundle this file with your app so the WebView loads it locally.

```html
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdn.jsdelivr.net/npm/@fiskil/link@0.1.6-beta/dist/fiskil-link.umd.js"></script>
</head>
<body>
  <script>
    function startLink(authSessionId) {
      var flow = FiskilLink.link(authSessionId);

      flow
        .then(function(result) {
          sendToNative('success', { consentID: result.consentID });
        })
        .catch(function(err) {
          sendToNative('error', { code: err.code, message: err.message });
        });
    }

    function sendToNative(type, payload) {
      var message = JSON.stringify({ type: type, payload: payload });

      // iOS (WKWebView)
      if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.fiskil) {
        window.webkit.messageHandlers.fiskil.postMessage(message);
        return;
      }

      // Android (WebView)
      if (window.FiskilBridge) {
        window.FiskilBridge.onResult(message);
        return;
      }
    }
  </script>
</body>
</html>
```

The `sendToNative` function detects which platform it's running on and routes the message to the appropriate native handler. The native side calls `startLink()` to kick off the flow once the page is loaded.

iOS Integration (WKWebView) [#ios-integration-wkwebview]

Load the bridge HTML page in a `WKWebView`. There are two key integration points: registering a script message handler so the JavaScript `sendToNative` function can reach your Swift code, and calling `startLink()` once the page finishes loading.

**Register the JS bridge** by adding a `WKScriptMessageHandler` with the name `fiskil` -- this matches the `window.webkit.messageHandlers.fiskil` call in the bridge HTML:

```swift
let configuration = WKWebViewConfiguration()
configuration.userContentController.add(self, name: "fiskil")

let webView = WKWebView(frame: view.bounds, configuration: configuration)
```

**Start the flow** once the page has loaded by calling `startLink()` with the auth session ID via `evaluateJavaScript`:

```swift
func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
    webView.evaluateJavaScript("startLink('\(authSessionId)')")
}
```

**Handle the result** in your `WKScriptMessageHandler` implementation. The message body is the JSON string sent by `sendToNative`:

```swift
func userContentController(
    _ userContentController: WKUserContentController,
    didReceive message: WKScriptMessage
) {
    // message.body is the JSON string: {"type": "success"|"error", "payload": {...}}
    // Parse and handle accordingly
}
```

<Callout type="info">
  Bundle the `fiskil-link.html` file in your app and load it with `loadFileURL(_:allowingReadAccessTo:)`. Make sure JavaScript and DOM storage are enabled on the WebView configuration.
</Callout>

Android Integration (WebView) [#android-integration-webview]

Load the bridge HTML page in an Android `WebView`. The two key integration points are: adding a JavaScript interface so `window.FiskilBridge.onResult()` can reach your Kotlin code, and calling `startLink()` once the page finishes loading.

**Register the JS bridge** by adding a JavaScript interface named `FiskilBridge` -- this matches the `window.FiskilBridge` call in the bridge HTML:

```kotlin
val webView = WebView(this).apply {
    settings.javaScriptEnabled = true
    settings.domStorageEnabled = true
}

webView.addJavascriptInterface(object {
    @JavascriptInterface
    fun onResult(message: String) {
        // message is the JSON string: {"type": "success"|"error", "payload": {...}}
        // Parse and handle accordingly
    }
}, "FiskilBridge")
```

**Start the flow** once the page has loaded by calling `startLink()` with the auth session ID:

```kotlin
webView.webViewClient = object : WebViewClient() {
    override fun onPageFinished(view: WebView?, url: String?) {
        view?.evaluateJavascript("startLink('$authSessionId')", null)
    }
}

webView.loadUrl("file:///android_asset/fiskil-link.html")
```

<Callout type="info">
  Place the `fiskil-link.html` file in your `assets/` directory. Note that `@JavascriptInterface` methods are called on a background thread -- switch to the main thread before updating UI.
</Callout>

Institution Selection Strategies [#institution-selection-strategies]

You have two options for how users select their institution (bank or energy provider) during the consent flow.

Option A: Use Fiskil's Built-In Institution List [#option-a-use-fiskils-built-in-institution-list]

The simplest approach. When you create an Auth Session **without** an `institution_id`, the consent flow rendered by the Link SDK begins with Fiskil's hosted institution picker. The user selects their institution, then proceeds to authenticate.

No additional work is required -- just pass the `auth_session_id` to the Link SDK as shown above.

```json
{
  "end_user_id": "eu_12345"
}
```

Option B: Build Your Own Institution List [#option-b-build-your-own-institution-list]

For a fully native experience, you can build your own institution picker in your app and pass the selected `institution_id` when creating the Auth Session. This skips Fiskil's institution selection screen entirely, taking the user straight to authentication.

**Step 1: Fetch institutions from the API**

Call [`GET /v1/institutions`](/data-api/api-reference/institutions) with your `client_id` to retrieve the list of available institutions. You can filter by `industry` to show only banking or energy providers.

```bash
curl --request GET \
  --url 'https://api.fiskil.com/v1/institutions?industry=banking&client_id={client_id}' \
  --header 'accept: application/json; charset=UTF-8'
```

Each institution in the response includes fields you can use to build your UI:

| Field                       | Description                                              |
| --------------------------- | -------------------------------------------------------- |
| `id`                        | The institution ID to pass when creating an Auth Session |
| `name`                      | Display name of the institution                          |
| `icon`                      | URL to a square icon (suitable for list items)           |
| `logo`                      | URL to the full logo                                     |
| `industry`                  | `banking` or `energy`                                    |
| `status.connections.status` | `HEALTHY`, `DEGRADED`, or `OUTAGE`                       |

**Step 2: Render a native institution picker**

Use the institution data to build a native list or grid in your app. You can add search, filtering, and custom branding that matches your app's design.

**Step 3: Pass the selected institution ID**

When the user selects an institution, create the Auth Session with the `institution_id` parameter. The consent flow will skip the institution picker and go directly to the selected institution's login screen.

```bash
curl --request POST \
  --url https://api.fiskil.com/v1/auth/session \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "end_user_id": "eu_12345",
    "institution_id": "22"
  }'
```

Then pass the returned `session_id` to the Link SDK as normal. The user will skip institution selection and go straight to authentication.

<Callout type="info">
  Check the `status.connections.status` field before presenting an institution to users. If the status is `OUTAGE`, consider hiding the institution or showing a notice that it is temporarily unavailable.
</Callout>

Best Practices [#best-practices]

* **Enable JavaScript and DOM storage** in your WebView configuration -- the Link SDK requires both
* **Bundle the HTML page locally** rather than hosting it remotely, so the WebView loads instantly without a network request
* **Handle external links** by opening them in the system browser rather than inside the WebView (e.g., privacy policy or help links)
* **Support back navigation** so users can go back within the consent flow without dismissing the entire WebView
* **Clear WebView data** between sessions if multiple users share the same device
* **Test with sandbox credentials** on both iOS and Android before going live -- see the [Testing guide](/data-api/guides/core-concepts/testing) for details
* **Handle session expiry** gracefully -- Auth Sessions expire after 5 days, so create a new session if the user returns after a delay

Next Steps [#next-steps]

* Review the [Link SDK reference](/data-api/guides/link-widget/integrating-the-link-sdk) for the full list of options and error codes
* Set up [Webhooks](/data-api/guides/core-concepts/webhooks) to receive consent and data sync notifications
* See [Error Types](/data-api/api-reference/errors) for handling error codes returned by the SDK
* Read the [Best Practices](/data-api/guides/resources/best-practices) guide for general integration recommendations


---

# Renew Consents (/data-api/guides/resources/renew-consents)

A playbook for helping customers renew Data API consents before they expire.



Customer consent is not a "set and forget" connection. For privacy and regulatory reasons, consents have expiry dates to prevent unfettered access to a user's data. Your application needs a renewal process that helps users refresh their consent before access is interrupted.

This playbook explains how to identify expiring consents, notify customers, and create a renewal [Auth Session](/data-api/guides/core-concepts/auth-sessions) so users can update an existing consent without starting from scratch.

<Callout type="info">
  Consent renewal uses the existing consent's `arrangement_id`. The renewed consent uses the permissions from the existing consent, while the new consent period comes from your current team configuration in the Fiskil Console.
</Callout>

How Consent Expiry Works [#how-consent-expiry-works]

A consent can last for up to 12 months. The consent duration is configurable in the [Fiskil Console](https://console.fiskil.com/) as part of your consent flow setup, alongside data history, use case descriptions, and branding.

When a consent expires, your application may no longer be able to access the user's shared data. To avoid broken connections, notify users at least one month before expiry, or earlier depending on your product experience.

A good renewal workflow usually looks like this:

1. Find consents that are approaching expiry.
2. Notify affected users in your app, by email, SMS, or another owned channel.
3. Create a new Auth Session using the existing consent's `arrangement_id`.
4. Send the user through the consent update flow with [Fiskil Link](/data-api/guides/link-widget/integrating-the-link-sdk).
5. Listen for confirmation that the consent was updated.

Recommended Renewal Timeline [#recommended-renewal-timeline]

Start renewal outreach before the consent becomes urgent.

| Time before expiry | Recommended action                                                |
| ------------------ | ----------------------------------------------------------------- |
| 60-45 days         | Optional early reminder for low-frequency users.                  |
| 30 days            | Start your main renewal campaign.                                 |
| 14 days            | Show in-app prompts or banners.                                   |
| 7 days             | Increase urgency in messaging.                                    |
| 1-3 days           | Send a final reminder before the connection expires.              |
| After expiry       | Ask the user to reconnect before you attempt further data access. |

You can choose the exact timing, but avoid waiting until the final few days. Users may need time to log in to their institution, complete OTP verification, and select accounts.

Step 1: Find Consents Approaching Expiry [#step-1-find-consents-approaching-expiry]

Use the [Consents API](/data-api/api-reference/consents#list-consents) to query consents that are due to expire soon. Pass `active=true` with `expires_before` to find active consents expiring before an RFC3339 timestamp.

<Callout type="warning">
  Paginated consent responses are only supported in API version `v3`. Include the
  `X-Fiskil-Version: v3` header when using pagination parameters.
</Callout>

```bash
curl --request GET \
  --url "https://api.fiskil.com/v1/consent?active=true&expires_before=2026-07-09T00:00:00Z&page[size]=100" \
  --header "Authorization: Bearer ${access_token}" \
  --header "X-Fiskil-Version: v3" \
  --header "Accept: application/json"
```

Example response:

```json
{
  "consents": [
    {
      "account_ids": ["acc_123"],
      "active": true,
      "app_logo": "https://example.com/logo.png",
      "app_name": "Example App",
      "arrangement_id": "94549a73-a554-4b76-b824-d96898829751",
      "created_at": "2025-07-09T00:00:00Z",
      "duration": 31536000,
      "end_user_email": "customer@example.com",
      "end_user_id": "eu_2yRHN2ag2y4p8kCtm5DOeccZEXB",
      "expires_at": "2026-07-09T00:00:00Z",
      "institution_id": "11",
      "institution_logo": "https://example.com/institution-logo.png",
      "institution_name": "Example Bank",
      "institution_type": "bank",
      "last_accessed": "2026-06-09T00:00:00Z",
      "last_consent": "2025-07-09T00:00:00Z",
      "permissions": ["accounts", "balances", "transactions"],
      "termination_reason": ""
    }
  ],
  "links": {
    "next": "/v1/consent?active=true&expires_before=2026-07-09T00:00:00Z&page[after]=cursor_next",
    "prev": "/v1/consent?active=true&expires_before=2026-07-09T00:00:00Z&page[before]=cursor_prev"
  }
}
```

To find recently expired consents, query inactive consents and filter by `expires_before` or your own stored expiry timestamp.

```bash
curl --request GET \
  --url "https://api.fiskil.com/v1/consent?active=false&expires_before=2026-07-09T00:00:00Z" \
  --header "Authorization: Bearer ${access_token}" \
  --header "Accept: application/json"
```

Use the returned `arrangement_id`, `end_user_id`, `institution_id`, and `expires_at` values to decide which customers to contact and when.

Step 2: Notify the User [#step-2-notify-the-user]

Once you know which consents are approaching expiry, notify the user through your preferred channel.

Your message should clearly explain:

* Their current connection is due to expire.
* Renewal keeps their account or service connected.
* They will be redirected to their institution to confirm consent.
* They can review or update which accounts are shared.

Example in-app copy:

> Your bank connection expires soon
>
> To keep your account data up to date, renew your consent before 9 July 2026. You'll be asked to securely authenticate with your institution and confirm the accounts you want to share.

Avoid implying that consent renewal is automatic. The user must complete the institution flow themselves.

Step 3: Create a Renewal Auth Session [#step-3-create-a-renewal-auth-session]

To renew an existing consent, create a new Auth Session and pass the existing consent's `arrangement_id`. This tells Fiskil to launch an update flow for the current arrangement instead of creating an unrelated new connection.

<Callout type="info">
  Permissions come from the existing consent, not from the current team configuration.
</Callout>

For renewal:

* The renewed consent period comes from the current team configuration in the Fiskil Console.
* The `institution_id` can be included to keep the user on the same institution.
* `redirect_uri` and `cancel_uri` are required for redirect flows, but can be omitted when you are using the Link SDK.

```bash
curl --request POST \
  --url "https://api.fiskil.com/v1/auth/session" \
  --header "Authorization: Bearer ${access_token}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "end_user_id": "eu_2yRHN2ag2y4p8kCtm5DOeccZEXB",
    "arrangement_id": "94549a73-a554-4b76-b824-d96898829751",
    "institution_id": "11"
  }'
```

Example response:

```json
{
  "id": "5qcql2s0bn9qfh1m5qd1sl4gth",
  "session_id": "ea564d-56012s4-6ds4564",
  "auth_url": "https://auth.fiskil.com/consent?session=ea564d-56012s4-6ds4564",
  "expires_at": 1621083785
}
```

Store the `session_id` for debugging and audit purposes, then pass it to Link.

Step 4: Send the User Through Link [#step-4-send-the-user-through-link]

Use the [Fiskil Link SDK](/data-api/guides/link-widget/integrating-the-link-sdk) to launch the consent update flow inside your application.

```typescript
import { link } from '@fiskil/link';

const flow = link('ea564d-56012s4-6ds4564');

try {
  const result = await flow;
  console.log('Renewed consent:', result.consentID);
} catch (err) {
  console.error('Renewal failed:', (err as any).code);
}
```

During the update flow, the user will typically:

* Review the consent request.
* Authenticate with their institution.
* Confirm the accounts they want to share.
* Return to your application once complete.

For update flows, previously shared accounts are preselected where supported. The user can still review and adjust their selection before confirming the renewed consent.

Once the user completes the flow, continue with your normal post-consent handling. For example, refresh account data, update the user's connection status, or remove renewal banners from your application.

Step 5: Track the Result [#step-5-track-the-result]

Track consent renewal using your Link result, redirect flow, and webhooks. Webhooks are the most reliable server-side signal because they do not depend on the user returning to your application successfully.

Fiskil supports consent webhook events, including `consent.received`, `consent.updated`, and `consent.revoked`. A `consent.updated` event is emitted when our system completes the renewal through `authorize_callback` and confirms that an access token exists.

Example webhook payload:

```json
{
  "publish_time": "2026-06-09T05:10:03.957Z",
  "message_id": "9061924608716421",
  "data": {
    "event": "consent.updated",
    "consent_id": "con_123456",
    "end_user_id": "eu_2yRHN2ag2y4p8kCtm5DOeccZEXB",
    "client_id": "your_client_id",
    "institution_id": "11"
  }
}
```

When you receive `consent.updated`, mark the connection as renewed and store the latest consent expiry date. Use `message_id` for idempotency so duplicate webhook deliveries do not trigger duplicate work.

Handling Cancelled or Failed Renewals [#handling-cancelled-or-failed-renewals]

If a user cancels or fails the renewal flow, Link rejects with an error code. In a redirect flow, Fiskil redirects the user to your `cancel_uri` with error details.

Example cancelled redirect:

```text
https://yourapp.com/consent/cancelled?error=access_denied&error_type=CONSENT_ENDUSER_DENIED&error_id=err_acde070d-8c4c-4f0d-9d8a-162843c10333
```

| Error type                          | What it means                                                         | Recommended action                                                   |
| ----------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `CONSENT_ENDUSER_DENIED`            | The user cancelled or denied consent.                                 | Let the user retry when ready.                                       |
| `CONSENT_OTP_FAILURE`               | The user failed OTP verification.                                     | Ask the user to retry and check their institution details.           |
| `CONSENT_TIMEOUT`                   | The flow timed out or was abandoned.                                  | Create a new Auth Session and let the user try again.                |
| `CONSENT_ENDUSER_INELIGIBLE`        | The institution did not allow the user to share the selected account. | Ask the user to check account eligibility with their institution.    |
| `CONSENT_UPSTREAM_PROCESSING_ERROR` | The institution encountered an error.                                 | Ask the user to retry. Raise a support ticket if the issue persists. |

Best Practices [#best-practices]

* Renew before expiry, not after. Start outreach at least 30 days before expiry so users have time to complete the flow.
* Use the existing `arrangement_id`. This tells Fiskil that the Auth Session is intended to update an existing arrangement rather than create an unrelated new one.
* Keep the message user-friendly. Explain the benefit: renewing consent keeps their connection active. Avoid regulatory language unless your product requires it.
* Handle retries gracefully. Users may abandon the flow, fail OTP, or need to come back later. Make it easy to restart renewal.
* Listen for webhooks. Webhooks help your application react when consent is updated or revoked without relying only on client-side completion. Fiskil retries failed webhook deliveries up to five times with backoff intervals.


---

# Troubleshooting (/data-api/guides/support/troubleshooting)

Troubleshoot common integration issues and find the right support resources.



If something isn't working as expected, this page will help you troubleshoot common issues and guide you to the right place to get help.

Where to Start [#where-to-start]

Before raising a support request, we recommend checking:

1. Has the user successfully linked their institution and granted consent?
2. Are your API requests authenticated with a valid access token?
3. Are you receiving webhook events correctly?
4. Have you completed the steps in the [Quick Start](/docs/data-api/guides/getting-started/quick-start)?

If you've confirmed these steps and are still encountering issues, continue below.

Common Issues [#common-issues]

Connection or Consent Flow Failing [#connection-or-consent-flow-failing]

If users abandon or fail to complete the institution linking process, you may encounter errors such as:

* `CONSENT_OTP_FAILURE`
* `CONSENT_UPSTREAM_PROCESSING_ERROR`
* `CONSENT_ENDUSER_DENIED`
* `CONSENT_TIMEOUT`
* `AUTH_SESSION_CANCELLED`

These errors typically occur within the third-party institution's consent process. Review the [Error Types](https://docs.fiskil.com/errors#error-types) for causes, suggested responses, and retry strategies.

Webhooks Not Received [#webhooks-not-received]

If webhook events are not arriving:

* Verify the HMAC signature in the `X-Fiskil-Signature` header to ensure payload authenticity
* Check your server logs for incoming POST requests
* Ensure your server is returning a `2xx` status code
* Confirm that your webhook endpoint is correctly registered in the Fiskil Console under [Settings > Webhooks](https://console.fiskil.com)

See the [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks) for implementation details and security verification steps.

Data Not Available [#data-not-available]

If an API response returns no data:

* Use the [Consent API](/docs/data-api/api-reference/consents) to check if the user has an active consent
* Ensure that the `end_user_id` is valid and that the user has completed a connection
* Confirm that a relevant webhook (e.g. `transactions.sync.completed`) has been received

Data is only available after consent has been granted and the data sync has completed.

For more information, see:

* [Consent Overview](/docs/data-api/guides/core-concepts/consents)
* [End Users Guide](/docs/data-api/guides/core-concepts/end-users)

Raising a Support Request [#raising-a-support-request]

If you're blocked and can't resolve the issue through documentation:

Gather the following (where available):

* Environment (sandbox or production)
* Timestamps and request/response logs
* `error_id` (from query string or webhook)
* `session_id` (if applicable)
* `end_user_id`

Submit a request via the Fiskil Support Desk: [https://fiskil.atlassian.net/servicedesk/customer/portal/6](https://fiskil.atlassian.net/servicedesk/customer/portal/6)

We recommend providing as much detail as possible to help our team resolve your issue efficiently.

Helpful Resources [#helpful-resources]

* [Launch Checklist](/docs/data-api/guides/resources/go-live-checklist)
* [End Users](/docs/data-api/guides/core-concepts/end-users)
* [Consent](/docs/data-api/guides/core-concepts/consents)
* [Webhooks Guide](/docs/data-api/guides/core-concepts/webhooks)
* [Error Reference](https://docs.fiskil.com/errors)


---

# Registro de Cambios (/es/data-holder/changelog)

Todos los cambios realizados a la documentación se listan aquí a partir del 10-08-2023.



Todos los cambios realizados a la documentación se listan aquí a partir del 10-08-2023.

07-03-2025 (v1.5.0) [#07-03-2025-v150]

* Agrega filtro `"open-status"` a la API de Energía `Fetch Accounts for Customer`. Este parámetro es requerido para soportar la API CDR `Get All Accounts` que tiene un filtro en el estado de apertura de cuenta. Los valores válidos son `"ALL"`, `"OPEN"`, o `"CLOSED"`. Solo deben retornarse las cuentas solicitadas con el estado de apertura coincidente.

06-08-2024 (v1.4.0) [#06-08-2024-v140]

* Actualiza la descripción del campo "phoneNumber" en la respuesta de búsqueda de cliente para soportar entrega por SMS de OTP de autenticación
* Elimina campos innecesarios "givenName", "familyName", "updatedAt", "address", "emailVerified", "email", y "phoneNumberVerified" de la respuesta de búsqueda de cliente

06-08-2024 (v1.3.3) [#06-08-2024-v133]

* Clarificación de propiedades **PaymentSet.To** de Pagos Programados bancarios. Los detalles completos de beneficiario y cuenta deben retornarse con campos **accountID** y **payeeID**.
* Etiqueta "Energy" agregada a endpoints de la industria energética.

05-08-2024 (v1.3.2) [#05-08-2024-v132]

* Agrega parámetros `"is-owned"` y `"open-status"` a la solicitud `Obtain balances for a specified list of accounts` (POST `/v1/banking/customer/{customerId}/accounts/balances`)
* Agrega parámetros `"is-owned"` y `"open-status"` a la solicitud `Obtain direct debit authorisations for a specified list of accounts` (POST `/v1/banking/customer/{customerId}/accounts/direct-debits`)
* Agrega parámetros `"is-owned"` y `"open-status"` a la solicitud `Obtain scheduled payments for a specified list of accounts` (POST `/v1/banking/customer/{customerId}/payments/scheduled`)

05-08-2024 (v1.3.1) [#05-08-2024-v131]

* Agrega propiedad "users" al objeto de respuesta BankingAccountDetailV3 en la especificación de API

Versión 1.0.0 [#versión-100]

Agregado [#agregado]

* Lanzamiento inicial del Data Holder
* Soporte para esquemas personalizados
* Soporte de múltiples especificaciones (CDR, FDX, PSD2)


---

# Guías del Data Provider (/es/data-holder/guides)

Guías completas para integrar y usar Fiskil Data Provider.



Bienvenido a las guías del Proveedor de Datos de Fiskil. Aquí encontrará toda la documentación que necesita para comenzar con el intercambio de datos con permiso del usuario.

<Cards>
  <Card title="Introducción" href="/es/data-holder/guides/introduction" icon={<DatabaseRestore />}>
    Aprenda sobre el Proveedor de Datos de Fiskil y cómo funciona.
  </Card>

  <Card title="Inicio Rápido" href="/es/data-holder/guides/get-started/quickstart" icon={<DatabaseRestore />}>
    Comience con su primera integración en minutos.
  </Card>
</Cards>


---

# Autenticación (/es/data-holder/platform-api/authentication)

Autentique en la API de Plataforma usando credenciales de cliente para gestionar productos programáticamente.



La API de Plataforma utiliza credenciales de cliente OAuth 2.0 para la autenticaci\u00f3n. Esta gu\u00eda le muestra c\u00f3mo obtener y usar tokens de acceso.

Requisitos previos [#requisitos-previos]

Debe tener acceso al Portal de Productos en la [Consola de Fiskil](https://console.fiskil.com/) para generar claves de API.

Generar credenciales de API [#generar-credenciales-de-api]

1. Navegar a Claves de API [#1-navegar-a-claves-de-api]

En la Consola de Fiskil, navegue a **Claves de API** en la barra lateral.

2. Seleccionar permisos [#2-seleccionar-permisos]

Genere credenciales con los alcances apropiados de gesti\u00f3n de productos:

| Alcance                       | Descripci\u00f3n                                                  |
| ----------------------------- | ----------------------------------------------------------------- |
| `api:provider.products.read`  | Listar y ver productos a trav\u00e9s de endpoints de API internos |
| `api:provider.products.write` | Crear, actualizar y eliminar productos                            |

> Los endpoints de API p\u00fablicos son visibles globalmente y no requieren permisos de lectura.

3. Almacenar credenciales de forma segura [#3-almacenar-credenciales-de-forma-segura]

Despu\u00e9s de generar, la Consola muestra un par de **Client ID** y **Client Secret**. Almac\u00e9nelos de forma segura: los necesitar\u00e1 para obtener tokens de acceso.

<Callout type="warn">
  El secreto del cliente solo se muestra una vez. Almac\u00e9nelo en un lugar seguro como un gestor de secretos.
</Callout>

Obtener un token de acceso [#obtener-un-token-de-acceso]

Intercambie sus credenciales de cliente por un token de acceso de corta duraci\u00f3n:

```bash title="cURL"
curl -X POST https://api.fiskil.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'
```

```javascript title="Node.js"
const response = await fetch('https://api.fiskil.com/v1/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: process.env.FISKIL_CLIENT_ID,
    client_secret: process.env.FISKIL_CLIENT_SECRET
  })
});

const { token, expires_in } = await response.json();
```

```python title="Python"
import requests

response = requests.post(
    'https://api.fiskil.com/v1/token',
    json={
        'client_id': 'your_client_id',
        'client_secret': 'your_client_secret'
    }
)

data = response.json()
token = data['token']
expires_in = data['expires_in']
```

Respuesta [#respuesta]

```json
{
  "token": "eyJhbGc....",
  "expires_in": 900
}
```

| Campo        | Tipo    | Descripci\u00f3n                                                                                     |
| ------------ | ------- | ---------------------------------------------------------------------------------------------------- |
| `token`      | string  | El token de acceso para usar en el encabezado `Authorization` para solicitudes de API posteriores.   |
| `expires_in` | integer | Per\u00edodo de validez del token en segundos. El valor predeterminado es 900 segundos (15 minutos). |

Realizar solicitudes autenticadas [#realizar-solicitudes-autenticadas]

Incluya el token de acceso en el encabezado `Authorization` usando el esquema Bearer:

```bash
curl -X GET https://api.fiskil.com/v1/data-provider/cdr/products \
  -H "Authorization: Bearer eyJhbGc...."
```

<Callout type="info">
  Los tokens expiran despu\u00e9s de 15 minutos. Implemente l\u00f3gica de actualizaci\u00f3n de tokens en su aplicaci\u00f3n para obtener nuevos tokens antes del vencimiento.
</Callout>

Respuestas de error [#respuestas-de-error]

| C\u00f3digo de Estado   | Descripci\u00f3n                                  |
| ----------------------- | ------------------------------------------------- |
| `401 Unauthorized`      | Credenciales inv\u00e1lidas o expiradas           |
| `403 Forbidden`         | Permisos insuficientes para el alcance solicitado |
| `429 Too Many Requests` | L\u00edmite de tasa excedido                      |

Credenciales inv\u00e1lidas [#credenciales-invu00e1lidas]

```json
{
  "error": "invalid_client",
  "error_description": "The client credentials are invalid"
}
```

**Soluci\u00f3n:** Verifique que su client ID y secreto sean correctos y no hayan sido revocados.

Permisos insuficientes [#permisos-insuficientes]

```json
{
  "error": "insufficient_scope",
  "error_description": "The access token does not have the required scope"
}
```

**Soluci\u00f3n:** Genere nuevas credenciales de API con los alcances requeridos.

Mejores pr\u00e1cticas de seguridad [#mejores-pru00e1cticas-de-seguridad]

* **Nunca exponga credenciales** en c\u00f3digo del lado del cliente o control de versiones
* **Rote los secretos regularmente** y revoque las credenciales no utilizadas
* **Use variables de entorno** o un gestor de secretos para el almacenamiento de credenciales
* **Implemente cach\u00e9 de tokens** para reducir las solicitudes de autenticaci\u00f3n
* **Monitoree el uso de la API** a trav\u00e9s de la Consola para detectar actividad inusual


---

# Ejemplos (/es/data-holder/platform-api/examples)

Vea ejemplos de payloads para gestionar diferentes tipos de productos.



La API de Plataforma de Fiskil permite gestionar diferentes tipos de productos espec\u00edficos de dominio. Vea a continuaci\u00f3n ejemplos de c\u00f3mo crear productos relacionados con dominios espec\u00edficos.

Crear producto de ahorros [#crear-producto-de-ahorros]

```bash title="cURL"
curl -X POST https://api.fiskil.com/v1/data-provider/cdr/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
  "additional_information": {
    "eligibility_uri": "https://www.bank.com/legal/savings-account-target-market-determination/",
    "fees_and_pricing_uri": "https://www.bank.com/legal/savings-rate-fee-guide/",
    "overview_uri": "https://www.bank.com/save/",
    "terms_uri": "https://www.bank.com/legal/terms-conditions-savings/"
  },
  "brand": "Your Bank",
  "brand_name": "Your Bank Brand",
  "description": "Your Bank gets you a fee free, high yield savings account.",
  "is_tailored": false,
  "name": "Savings",
  "product_category": "TRANS_AND_SAVINGS_ACCOUNTS",
  "fees": [
    {
      "name": "Account Keeping Fee",
      "fixed_amount": { "amount": "0.00" },
      "additional_value": "month",
      "fee_type": "PERIODIC",
      "fee_method_u_type": "fixedAmount"
    }
  ],
  "eligibility": [
    { "eligibility_type": "NATURAL_PERSON", "additional_value": "Not available for joint applicants" },
    { "eligibility_type": "RESIDENCY_STATUS", "additional_value": "Australian Citizen or Permanent Resident" },
    { "eligibility_type": "MIN_AGE", "additional_value": "18" }
  ],
  "constraints": [{ "constraint_type": "MAX_BALANCE", "additional_value": "250000" }],
  "deposit_rates": [
    {
      "deposit_rate_type": "VARIABLE",
      "rate": "0.0415",
      "application_frequency": "P1M",
      "application_type": "PERIODIC",
      "tiers": [
        {
          "maximumValue": "250000.00",
          "minimumValue": "5000.00",
          "name": "Amount",
          "unitOfMeasure": "DOLLAR"
        }
      ]
    }
  ],
  "features": [
    { "feature_type": "OTHER", "additional_info": "Pay Anyone (Direct Entry)" },
    { "feature_type": "UNLIMITED_TXNS", "additional_info": "Unlimited electronic transactions" },
    { "feature_type": "DIGITAL_BANKING", "additional_info": "Mobile App" },
    { "feature_type": "DIGITAL_BANKING", "additional_info": "Internet Banking" }
  ]
}'
```

Crear producto de pr\u00e9stamo [#crear-producto-de-pru00e9stamo]

```bash title="cURL"
curl -X POST https://api.fiskil.com/v1/data-provider/cdr/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
  "additional_information": {
    "eligibility_uri": "https://www.bank.com/legal/secured-personal-loan-target-market-determination/",
    "fees_and_pricing_uri": "https://www.bank.com/legal/credit-fees-guide/"
  },
  "brand": "Your Bank",
  "brand_name": "Your Bank Brand",
  "description": "Secured personal loan with personalised interest rates.",
  "is_tailored": false,
  "name": "Personal Loan",
  "product_category": "PERS_LOANS",
  "fees": [
    { "name": "Establishment fee", "fixed_amount": { "amount": "295.00" }, "fee_type": "UPFRONT", "fee_method_u_type": "fixedAmount" },
    { "name": "Late Payment Fee", "fixed_amount": { "amount": "0.00" }, "fee_type": "EVENT", "fee_method_u_type": "fixedAmount" },
    { "name": "Early Repayment Fee", "fixed_amount": { "amount": "0.00" }, "fee_type": "EVENT", "fee_method_u_type": "fixedAmount" }
  ],
  "eligibility": [
    { "eligibility_type": "NATURAL_PERSON", "additional_value": "Not available for joint borrowers" },
    { "eligibility_type": "RESIDENCY_STATUS", "additional_value": "Australian Citizen or Permanent Resident" },
    { "eligibility_type": "MIN_AGE", "additional_value": "18" }
  ],
  "constraints": [
    { "constraint_type": "MIN_LIMIT", "additional_value": "10000.00" },
    { "constraint_type": "MAX_LIMIT", "additional_value": "100000.00" }
  ],
  "lending_rates": [{
    "lending_rate_type": "FIXED",
    "comparison_rate": "0.1217",
    "repayment_type": "PRINCIPAL_AND_INTEREST",
    "rate": "0.1174",
    "additional_value": "P7Y",
    "application_type": "MATURITY",
    "interest_payment_due": "IN_ARREARS",
    "tiers": [
      {
        "maximumValue": "250000.00",
        "minimumValue": "5000.00",
        "name": "Amount",
        "unitOfMeasure": "DOLLAR"
      }
    ]
  }],
  "features": [
    { "feature_type": "OTHER", "additional_info": "Sin tarifas continuas", "additional_value": "No ongoing fees" },
    { "feature_type": "OTHER", "additional_info": "Sin penalizaci\u00f3n por pago anticipado", "additional_value": "No early repayment fees" },
    { "feature_type": "OTHER", "additional_info": "Pago semanal, quincenal o mensual", "additional_value": "Repayment frequency" }
  ]
}'
```


---

# Introducción (/es/data-holder/platform-api/introduction)

Gestione programáticamente los recursos de su plataforma Fiskil Data Provider.



La API de Plataforma proporciona acceso program\u00e1tico a funciones administrativas en la plataforma Fiskil Data Provider. Utilice estas APIs para automatizar la gesti\u00f3n de productos, integrar con sus pipelines de CI/CD y construir herramientas personalizadas.

APIs disponibles [#apis-disponibles]

<CardGroup cols={2}>
  <Card title="API de Productos" icon="box" href="/es/data-holder/platform-api/createProduct">
    Crear, actualizar, listar y eliminar productos bancarios CDR.
  </Card>

  <Card title="API de Consentimientos" icon="file-signature" href="/es/data-holder/platform-api/listConsents">
    Liste y gestione los consentimientos autorizados por sus clientes.
  </Card>
</CardGroup>

URL base [#url-base]

```
https://api.fiskil.com/v1/data-provider
```

Especificación OpenAPI [#especificación-openapi]

Descargue la especificación OpenAPI completa de la API de Plataforma para generar clientes, importarla en herramientas de API o explorar el esquema sin conexión.

<Card title="Descargar Especificación OpenAPI de Plataforma" icon="download" href="/openapi/holder-platform-api.json">
  Obtenga la última especificación OpenAPI 3.0 de la API de Plataforma.
</Card>


---

# Custom Schema (/data-holder/api-reference/custom-schema)

Use the power of OpenAPI to build your Open Data environment



OpenAPI [#openapi]

To configure your custom Open Data environment you share an OpenAPI Schema with Fiskil that defines your resource server API. This schema contains:

* Your endpoints
* Permissions required to access each endpoint

Endpoint Requirements [#endpoint-requirements]

The paths in your endpoints must contain `/customer/{customerId}` so Fiskil can request the data for the user who authorised sharing. For example:

```yaml
paths:
  /v1/customer/{customerId}/pay:
    get:
      description: Shows the users pay information e.g. salary, pay frequency, Year To Date (YTD) earnings.
      operationId: getPayInformation
      parameters:
        - description: ID of a customer.
          explode: false
          in: path
          name: customerId
          required: true
          schema:
            type: string
          style: simple
```

The `customer/{customerId}` path parameter is required to ensure data from the correct customer is accessed. Third parties requesting data from your environment don't provide the `customer/{customerId}` in their request, Fiskil trims this from the API endpoint. For example: you might provide an OpenAPI definition with the following endpoints:

* `/v1/customer/{customerId}/pay`
* `/v1/customer/{customerId}/payslips`
* `/v1/customer/{customerId}/payslips/{id}`

Your Fiskil Open Data API will expose the following endpoints:

* `/v1/pay`
* `/v1/payslips`
* `/v1/payslips/{id}`

The customer ID in the request to your server is set based on the user associated with the access token used to request the data.

Scopes [#scopes]

Open ID Connect Scopes are used to authorise the sharing of specific datasets from your users. Your users review the scopes being requested by third parties so they know exactly what data they are sharing. Fiskil uses two OpenAPI extensions to define the scopes required to access your data.

1. Data Sharing endpoints must have a `x-fiskil-scopes` extension defining the scopes that must be authorised by the user to access the data
2. The `info` block must contain a `x-fiskil-scopeset` extension that defines the list of scopes supported and descriptions of them

For example:

```yaml
info:
  title: Mock Payroll API
  x-fiskil-scopeset:
    "payroll:pay:read":
      cluster_language: "Payroll - Read pay information"
      permission_language:
        - "Annual Salary"
        - "Pay Frequency"
        - "YTD Earnings"
paths:
  /v1/customer/{customerId}/pay:
    get:
      description: Shows the users pay information e.g. salary, pay frequency, Year To Date (YTD) earnings.
      summary: Get Pay Information
      operationId: getPayInformation
      parameters:
        - description: ID of a customer.
          explode: false
          in: path
          name: customerId
          required: true
          schema:
            type: string
          style: simple
      x-fiskil-scopes:
        - 'payroll:pay:read'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePayInformation'
          description: Success
      summary: Get Pay Information
```

In this example the `x-fiskil-scopeset` extension on the `info` element lists the available scopes: `payroll:pay:read`. The `cluster_language` field presents a high-level description of the data that is shared. The `permissions_language` field shows the exact pieces of data that fall under this scope. The `x-fiskil-scopes` extension on the `getPayInformation` operation shows that the `payroll:pay:read` scope is required if a third party wants to access the `pay` dataset. This information is shown to the end user during authorisation Scope Preview

Uploading your OpenAPI Specification [#uploading-your-openapi-specification]

You provide your OpenAPI Specification to Fiskil through the Fiskil Data Provider console. Navigate to the Resource Server Settings Menu and upload your specification. The Fiskil platform will validate your OpenAPI document against the requirements listed above. Once you've uploaded your specification, develop your resource server to implement your OpenAPI specification. After completing both these steps your environment is ready for testing. Download a full example of a Fiskil-compatible OpenAPI definition including customer ID path parameters and scope definitions

Extension Reference [#extension-reference]

x-fiskil-scopeset [#x-fiskil-scopeset]

**Parent element**: `info`\
**Type**: `Map<string, object>`\
**Object properties**:

```yaml
cluster_language: string
permission_language: List<string>
```

**Example**:

```yaml
info:
  x-fiskil-scopeset:
    payroll:pay:read:
      cluster_language: Payroll - Read pay information
      permission_language:
        - Annual Salary
        - Pay Frequency
        - YTD Earnings
```

x-fiskil-scopes [#x-fiskil-scopes]

**Parent element**: `method`\
**Type**: `List<string>`\
All values within the list must be present as a key in the `x-fiskil-scopeset` map.\
**Example**:

```yaml
paths:
  /v1/customer/{customerId}/pay:
    get:
      description: Shows the users pay information e.g. salary, pay frequency, Year To Date (YTD) earnings.
      x-fiskil-scopes:
        - payroll:pay:read
      # Remaining method content excluded...
```


---

# Frequently Asked Questions (/data-holder/api-reference/cdr-reference/cdr-faqs)

Common questions about Consumer Data Right implementation, compliance, and operations for data holders using Fiskil.



This guide addresses common questions about implementing and operating under the Consumer Data Right (CDR) framework using Fiskil's platform.

<Callout type="info">
  This information is for guidance only and should not be considered legal advice. Always consult with legal counsel and refer to the official CDR Rules and Standards for authoritative guidance.
</Callout>

***

CDR Data Fundamentals [#cdr-data-fundamentals]

<AccordionGroup>
  <Accordion title="What is a Consumer data request?">
    Consumer data requests are made by an accredited person to a primary data holder. The requests are made using the data holder's consumer data request service. Consumer data is either required or voluntary.

    Accredited persons can request the CDR consumer's required consumer data, voluntary consumer data, or both from the data holder. The data holder must disclose any requested required consumer data to the accredited person who made the request. The data holder may (but is not required to) disclose the voluntary consumer data that it is authorised to disclose.
  </Accordion>

  <Accordion title="What is a complex request?">
    If a consumer data request is made on behalf of a secondary user, or it relates to a joint or partnership account, as a nominated representative, or a large customer (in the case of Energy including commercial and industrial customers (C\&I customers)) it will be considered a complex request.

    A large customer of an energy retailer is a customer that is 'large', i.e. a customer that is not a relevant customer, for the purposes of the Electricity Industry Act 2000 (Vic) (the Victorian Act) or the National Energy Retail Law (NERL).

    <Callout type="warn">
      Complex requests are due to be rolled out by 1 May 2024.
    </Callout>
  </Accordion>

  <Accordion title="What's the difference between the Consumer Data Right Rules and the Consumer Data Standards?">
    The CDR is legislated through the CDR Rules, which define the elements for consent, outline the accreditation framework and elaborate on the privacy aspects of the scheme.

    The Standards set out the technical requirements for sharing data under CDR. Under the CDR Rules, data holders must comply with the Standards.
  </Accordion>
</AccordionGroup>

***

Getting Set Up with Fiskil [#getting-set-up-with-fiskil]

<AccordionGroup>
  <Accordion title="What obligations does Fiskil handle, and what obligations do data holders need to address?">
    **Fiskil helps with the following bank or energy retailer obligations:**

    * Disclosing consumer data
    * Reporting at scheduled intervals (see 'What are data holder reporting requirements?')
    * Keeping appropriate records (see 'What are data holder record-keeping requirements?')
    * Complying with most of the relevant privacy safeguards

    **There are some obligations that must be handled in house. These include:**

    * Establishing dispute resolution arrangements (see 'What are data holder Dispute Resolution requirements?')
    * Complying with some of the relevant privacy safeguards, like having a CDR policy (see 'What are CDR Policy requirements?')
  </Accordion>

  <Accordion title="What are CDR Policy requirements?">
    Data holders must have a CDR policy that is separate from any existing privacy or information security policy. The policy needs to be available to consumers free of charge and in their preferred format (hard copy or digital).

    For more information on the required format and contents for a CDR policy, see the [OAIC's Guide to developing a CDR policy](https://www.oaic.gov.au/consumer-data-right/cdr-privacy-safeguard-guidelines). Data holders must take reasonable steps to establish and maintain internal practices, procedures and systems to ensure they are complying with their obligations under CDR (Privacy Safeguard 1).

    <Callout type="info">
      For more information, see Section 8 of the Compliance guide for data holders or Rule 7.2 in the CDR Rules. See also: Privacy Safeguard 1 - CCA, section 56ED.
    </Callout>
  </Accordion>

  <Accordion title="What are data holder dispute resolution requirements?">
    Internal Dispute Resolution [#internal-dispute-resolution]

    Banks and Energy retailers must have an Internal Dispute Resolution (IDR) process. It must meet the banks or energy retailer's standard complaints and dispute resolution rules, satisfying APRA, NERL or Energy Retail Code (Victoria). From November 2022, this entails creating, publishing, and updating procedures for handling small customer complaints, aligning with AS ISO 10002-2006.

    These rules apply only to complaints from CDR consumers, not other industry players. The complaint-handling process covers all CDR consumer complaints, including those about consumer data. While it doesn't extend to industry player's complaints, CDR participants should reasonably manage all complaints.

    <Callout type="info">
      The ACCC can review complaints from all other CDR participants.
    </Callout>

    External Dispute Resolution [#external-dispute-resolution]

    An energy retailer data holder must be a member of the relevant state or territory energy and water Ombudsman scheme. The Ombudsman schemes are:

    * Energy and Water Ombudsman (NSW) Limited
    * Energy and Water Ombudsman (Victoria) Limited
    * Office of the Energy and Water Ombudsman (Queensland)
    * Energy and Water Ombudsman (SA) Limited

    <Callout type="info">
      For more information, see Section 7.1 of the Compliance guide for data holders or Rule 9.3 in the CDR Rules for internal dispute resolution, and Rule 6.2 and Schedule 4, clause 5.2 in the CDR Rules for external dispute resolution.
    </Callout>
  </Accordion>

  <Accordion title="What are data holder record-keeping requirements?">
    CDR Rule 9.3 mandates data holders to maintain records of:

    * Consumer data sharing authorisations, amendments, and withdrawals
    * Notifications of consent withdrawals
    * Primary data holder's requests for Shared Responsibility (SR) data from secondary data holders, with responses
    * Secondary data holder's SR data requests from primary data holders, with responses or reasons for refusal
    * Disclosures of CDR data in response to consumer requests
    * White labelled product data disclosure agreements
    * Instances of refusing CDR data disclosure with relevant grounds
    * CDR complaint data including received, resolved complaints and resolution times
    * Processes for obtaining consumer data authorisation, recorded via videos or alternative visuals

    <Callout type="warn">
      Records must have timestamps and be retained for 6 years, containing necessary personal info as per CDR Rules.
    </Callout>

    <Callout type="info">
      For more information, see Section 9 of the Compliance guide for data holders or Rule 9.3 in the CDR Rules.
    </Callout>
  </Accordion>
</AccordionGroup>

***

Customer Consents [#customer-consents]

<AccordionGroup>
  <Accordion title="How can a customer remove a consent?">
    One of the key elements of consent in the CDR is that it can be easily withdrawn (see rule 4.9). Data holders must allow consumers to withdraw their authorisation at any time by:

    **Using the consumer dashboard; or**

    **Using an alternative method of communication**, which must be simple. In addition, it:

    * Should be accessible and straightforward for a consumer to understand and use, and
    * May be written or verbal (such as through a telephone helpline). Where it is written, the communication may be sent by electronic means (such as email) or non-electronic means (such as by post).

    When a consumer withdraws consent [#when-a-consumer-withdraws-consent]

    When a consumer withdraws their consent by an alternative method of communication, the data holder must:

    * Stop sharing the consumer's data as soon as possible — **at most within 2 business days** of receiving the communication.

    Fiskil's approach [#fiskils-approach]

    <Callout type="info">
      Fiskil recommends the data holder direct a customer to the consumer dashboard by providing a link.
    </Callout>

    If for any reason the customer cannot access the consumer dashboard, the data holder can revoke the consent on the customer's behalf via lodging a support ticket on Fiskil's Jira Service desk. Support to revoke consent on the Administration Console is coming soon.

    Fiskil will notify any relevant accredited data recipient of the withdrawal in accordance with the Standards.
  </Accordion>
</AccordionGroup>

***

Reporting Requirements [#reporting-requirements]

<AccordionGroup>
  <Accordion title="What are data holder reporting requirements?">
    Biannual Reporting [#biannual-reporting]

    Data holders must submit CDR reports twice a year to the ACCC and OAIC.

    | Reporting Period     | Report Due By |
    | -------------------- | ------------- |
    | 1 January - 30 June  | 30 July       |
    | 1 July - 31 December | 30 January    |

    Key Points [#key-points]

    * Data holders' reporting begins when sharing consumer data under CDR Rules starts. Earlier sharing leads to earlier reporting, with Pilot phases also counted.
    * The report required by rule 9.4 is submitted to the ACCC and the OAIC via the CDR Participant Portal.
    * These online reports provide specific data, excluding plan data requests for energy retailers. Information must be current at the last day of the relevant reporting period.
    * Data holders that have multiple brands must submit a single report containing aggregated data that covers all their brands.

    Reporting Form Sections [#reporting-form-sections]

    | Section                           | Summary                                                                                                                                                                                                                                                                                                                                                                                             | Provided by |
    | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
    | **CDR complaint data summary**    | CDR complaint data for a data holder includes: Total CDR consumer complaints received, Categorisation of CDR complaints (per data holder's systems), Total resolved CDR consumer complaints, Average days for internal dispute resolution, CDR complaints referred to external resolution, CDR complaints resolved externally, CDR product data complaints received, reported individually          | Data Holder |
    | **CDR data requests received**    | The report mandates separate counts for: Product data requests, Direct consumer data requests, Accredited persons' consumer data requests on behalf of consumers. 'Received' means requests reached the data holder's system with potential responses. The report should cover 'successful' and 'unsuccessful' CDR data requests, including rejected ones due to exceeded traffic thresholds.       | Fiskil      |
    | **Refusals to disclose CDR data** | Data holders typically share required data upon valid requests, though refusals are possible in certain cases. Refusals must be communicated to the requester, using data standards error codes. Permissible refusal cases are identified via HTTP error codes. For example, requests that may cause physical, psychological, or financial harm or abuse, shown by HTTP error code '403 Forbidden'. | Fiskil      |

    <Callout type="info">
      For more information on complaint data, see Section 10.1.2 of the Compliance guide for data holders.
    </Callout>

    <Callout type="warn">
      Reporting isn't needed for attacks or non-CDR-related requests, or those due to maintenance, outage, or instability. Data holders don't have to record/report refusals for authorization requests based on safety, abuse, or other reasons outlined in CDR Rule 4.7.
    </Callout>

    Report Submission [#report-submission]

    A primary business contact, authorised business contact, primary IT contact or an authorised IT contact, can submit the report form by logging in to the Participant Portal at [https://portal.cdr.gov.au](https://portal.cdr.gov.au). Select 'Organisation' from the top navigation menu, then 'Reports' from the left side navigation pane.

    <Callout type="info">
      For more information, see Section 11 of the Participant Portal User Guide.
    </Callout>
  </Accordion>
</AccordionGroup>

***

Additional Resources [#additional-resources]

For comprehensive guidance on CDR compliance, refer to:

* [CDR Rules](https://www.legislation.gov.au/Details/F2020L00094)
* [Consumer Data Standards](https://consumerdatastandardsaustralia.github.io/standards/)
* [ACCC CDR Compliance Guide for Data Holders](https://www.accc.gov.au/by-business/consumer-data-right-cdr)
* [OAIC CDR Privacy Safeguard Guidelines](https://www.oaic.gov.au/consumer-data-right/cdr-privacy-safeguard-guidelines)
* [CDR Participant Portal](https://portal.cdr.gov.au)

<Callout type="info">
  This FAQ is regularly updated to reflect changes in CDR requirements. For the most current information, always refer to the official CDR Rules and Standards.
</Callout>


---

# Non-Functional Requirements (/data-holder/api-reference/cdr-reference/cdr-nfrs)

Technical requirements for CDR API performance, availability, traffic thresholds, and data quality standards.



The CDR APIs are required to follow a minimum standard of non-functional requirements. This section outlines those requirements and the respective responsibilities between Fiskil and the Customer (Data Holder).

<Callout type="info">
  These requirements are mandated by the Consumer Data Right standards and must be met for CDR compliance.
</Callout>

***

Responsibility Overview [#responsibility-overview]

| Non-Functional Requirement     | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Provided by        |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| **CDR Complaint Data Summary** | CDR complaint data for a data holder includes: Total CDR consumer complaints received, Categorisation of CDR complaints (per data holder's systems), Total resolved CDR consumer complaints (either reported in the current or previous period), Average days for internal dispute resolution, CDR complaints referred to external resolution, CDR complaints resolved externally, CDR product data complaints received, reported individually. For more information, see Section 10.1.2. of the Compliance guide for data holders. | Data Holder        |
| **Availability Requirements**  | Service availability requirement for data holders and AEMO: 99.5% per month                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Fiskil/Data Holder |
| **Traffic Thresholds**         | Defined thresholds for different types of traffic that can be throttled or rejected                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Fiskil             |
| **Data Quality**               | Ensuring product data is accurate, up to date and complete                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Data Holder        |
| **Performance Requirements**   | Response time requirements for different endpoint categories                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Fiskil/Data Holder |

***

Availability Requirements [#availability-requirements]

Service availability requirement for data holders and AEMO: **99.5% per month**

<Callout type="info">
  The unavailability of AEMO will mean that some requests cannot be fulfilled by a data holder making a Shared Responsibility Data Request. This will not be taken to mean that the data holder is unavailable.
</Callout>

***

Traffic Thresholds [#traffic-thresholds]

Fiskil automatically enforces these thresholds against third-party data recipients before requests reach your Resource Server. For capacity planning and edge protection guidance, see [Firewall](/data-holder/guides/security/firewall).

Calls in excess of the following traffic thresholds will be able to be freely throttled or rejected by a data holder without impact to their performance or availability requirements.

Traffic thresholds will be set using the following metrics:

* **Number of sessions per day** – the number of individual sessions initiated in a calendar day
* **Transactions Per Second (TPS)** – the number of concurrent transactions each second
* **Number of calls** – the number of end point calls initiated for a specified duration

<Tabs items={["Customer Present & Authorisation", "Unattended - Low Traffic", "Unattended - High Traffic"]}>
  <Tab value="Customer Present & Authorisation">
    For Customer Present and authorisation traffic the following traffic thresholds will apply:

    * Unlimited sessions per day
    * 10 TPS per customer
    * 50 TPS per Data Recipient Software Product
  </Tab>

  <Tab value="Unattended - Low Traffic">
    For Unattended traffic the following traffic thresholds will apply for **low traffic periods**:

    * 20 sessions per day, per customer, per Data Recipient Software Product
    * 100 total calls per session
    * 5 TPS per session
    * 50 TPS per Data Recipient Software Product
  </Tab>

  <Tab value="Unattended - High Traffic">
    For Unattended traffic during **high traffic periods** only best effort support is required.
  </Tab>
</Tabs>

Secure Traffic Thresholds [#secure-traffic-thresholds]

For secure traffic (both Customer Present and Unattended) the following traffic thresholds will apply based on active authorisations:

| Active Authorisations | Peak TPS Total |
| --------------------- | -------------- |
| 0 to 10,000           | 150 TPS        |
| 10,001 to 20,000      | 200 TPS        |
| 20,001 to 30,000      | 250 TPS        |
| 30,001 to 40,000      | 300 TPS        |
| 40,001 to 50,000      | 350 TPS        |
| 50,001 to 60,000      | 400 TPS        |
| More than 60,000      | 450 TPS        |

Public Traffic Thresholds [#public-traffic-thresholds]

For Public traffic (i.e. traffic to unauthenticated end points):

**300 TPS** total across all consumers (additive to secure traffic)

<Callout type="info">
  As traffic from Data Recipient Software Products to Data Holders will be shaped by the thresholds above, there are no specific thresholds applicable to secondary Data Holders.
</Callout>

***

Data Quality [#data-quality]

<Callout type="warn">
  If a Data Holder of CDR data is required or authorised under the Consumer Data Rules to disclose product data, the Data Holder must take reasonable steps to ensure that the product data is, having regard to the purpose for which it is held, **accurate, up to date and complete**.
</Callout>

Data Holders are required to be able to demonstrate that reasonable steps to maintain data quality of product data are being undertaken.

<Callout type="info">
  For the data quality requirements that apply to CDR data for which there are one or more CDR consumers, see Privacy Safeguard 11 (section 56EN of the Competition and Consumer Act 2010). There are requirements in Privacy Safeguard 11 for both Data Holders and Data Recipients. See Chapter 11 (Privacy Safeguard 11) of the OAIC's CDR Privacy Safeguard Guidelines for further information.
</Callout>

***

Performance Requirements [#performance-requirements]

The following response time requirements apply to different categories of endpoints:

| Performance Category        | Response Time                                  | Applies To                                                                                                                     |
| --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Unauthenticated**         | 1500ms                                         | All Unauthenticated end points not otherwise specified in a separate threshold                                                 |
| **High Priority**           | 1000ms                                         | All InfoSec end points including Dynamic Client Registration, CDR Arrangement Revocation, and specific high-priority endpoints |
| **Low Priority**            | 1500ms                                         | Customer Present calls to standard data endpoints                                                                              |
| **Unattended**              | 4000ms                                         | Unattended calls to data endpoints                                                                                             |
| **Large Payload**           | 6000ms                                         | Bulk operations and large data transfers                                                                                       |
| **AEMO Request**            | 1000ms (data holders) / 1500ms (AEMO requests) | Customer Present energy service point calls                                                                                    |
| **Large Secondary Request** | 1500ms (data holders) / 4500ms (AEMO requests) | Unattended energy service point calls and bulk operations                                                                      |

High Priority Endpoints (1000ms) [#high-priority-endpoints-1000ms]

<AccordionGroup>
  <Accordion title="InfoSec & Common Endpoints">
    * All InfoSec end points including Dynamic Client Registration
    * CDR Arrangement Revocation
    * Common: Get Status, Get Outages
  </Accordion>

  <Accordion title="Customer Present - High Priority">
    **Banking:**

    * Get Accounts

    **Energy:**

    * Get Energy Accounts
    * Get Energy Account Detail
    * Get Balance For Energy Account
    * Get Invoices For Account

    **Common:**

    * Get Customer
    * Get Customer Detail
  </Accordion>
</AccordionGroup>

Low Priority Endpoints (1500ms) [#low-priority-endpoints-1500ms]

<AccordionGroup>
  <Accordion title="Banking Endpoints">
    Customer Present calls to:

    * Get Account Detail
    * Get Account Balance
    * Get Bulk Balances
    * Get Balances For Specific Accounts
    * Get Transactions For Account
    * Get Transaction Detail
    * Get Payees
    * Get Payee Detail
    * Get Direct Debits For Account
    * Get Scheduled Payments For Account
    * Get Scheduled Payments Bulk
    * Get Scheduled Payments For Specific Accounts
  </Accordion>

  <Accordion title="Energy Endpoints">
    Customer Present calls to:

    * Get Agreed Payment Schedule
    * Get Concessions
    * Get Bulk Balances for Energy
    * Get Balances For Specific Energy Accounts
    * Get Bulk Invoices
    * Get Invoices For Specific Accounts
    * Get Billing For Account
  </Accordion>
</AccordionGroup>

Large Payload Endpoints (6000ms) [#large-payload-endpoints-6000ms]

<AccordionGroup>
  <Accordion title="Banking Large Payloads">
    * Get Bulk Direct Debits
    * Get Direct Debits For Specific Accounts
  </Accordion>

  <Accordion title="Energy Large Payloads">
    * Get Bulk Billing
    * Get Billing For Specific Account
  </Accordion>
</AccordionGroup>

AEMO-Related Performance Requirements [#aemo-related-performance-requirements]

<AccordionGroup>
  <Accordion title="AEMO Request (1000ms / 1500ms)">
    Customer Present calls to the following energy endpoints:

    * Get Service Points
    * Get Service Point Detail
    * Get DER For Service Point
  </Accordion>

  <Accordion title="Large Secondary Request (1500ms / 4500ms)">
    **Unattended calls to:**

    * Get Service Points
    * Get Service Point Detail
    * Get DER For Service Point

    **All calls to:**

    * Get Bulk Usage
    * Get Usage For Service Point
    * Get Usage For Specific Service Points
    * Get Bulk DER
    * Get DER For Specific Service Points
  </Accordion>
</AccordionGroup>

<Callout type="info">
  These performance requirements are measured at the 95th percentile and are critical for maintaining CDR compliance. Monitor your API performance closely to ensure these thresholds are consistently met.
</Callout>


---

# Errors (/data-holder/api-reference/cdr-reference/errors)

Standard error handling and status codes for CDR Resource Server integrations.



Most error handling is managed by Fiskil. However, in some cases your **Resource Server** must return errors to indicate why data cannot be shared.

Consistent use of error codes allows Data Recipients to understand outcomes and enables Fiskil to meet compliance and reporting requirements.

***

Status Codes [#status-codes]

403 — Forbidden [#403--forbidden]

Returned when Fiskil is not allowed to access the requested data.

Examples:

* Authentication failed between Fiskil and your Resource Server.
* The data request could cause physical or financial harm to an entity.

To distinguish a refusal from an ordinary 403, set the response header:

```http
X-Sharing-Refused: true
```

This distinction is required for CDR Data Holder reporting.

404 — Not Found [#404--not-found]

Returned when the resource ID in the request path does not exist for the customer.

Example:

```http
GET /v1/energy/customer/customer-id/accounts/not-a-real-account
```

If `not-a-real-account` is not linked to the given customer, return 404.

Also return 404 when the requested resource is associated with a blocked or suspended account. In this case, set the `X-Sharing-Refused` header as described above.

422 — Unprocessable Entity [#422--unprocessable-entity]

Returned when the resource ID in the request body does not exist for the customer.

Example:

```http
POST /v1/energy/customer/customer-id/accounts
{
  "data": {
    "accountIds": [
      "not-a-real-account"
    ]
  }
}
```

If the account ID is invalid, return 422.

Also return 422 when the account is blocked or suspended, with `X-Sharing-Refused` header set.

500 — Internal Server Error [#500--internal-server-error]

Returned for unexpected exceptions in your Resource Server.

Examples:

* Database connection loss
* Unhandled runtime error

***

Summary [#summary]

* Use 403, 404, 422, 500 consistently.
* Include the `X-Sharing-Refused` header where refusal is required to capture these events for CDR reporting.
* Return errors in the standard JSON format.


---

# Integration Requirements (/data-holder/api-reference/cdr-reference/integration-requirements)

Complete functional and non-functional requirements for integrating with Fiskil's CDR Data Provider platform.



This document provides an overview of what you need to do to integrate with Fiskil's Data Provider platform and build a compliant Consumer Data Right (CDR) integration.

***

What You're Building [#what-youre-building]

When you integrate with Fiskil as a CDR Data Holder, you're building a **Resource Server** — your API that exposes customer data according to CDR standards.

Responsibility Split [#responsibility-split]

**Fiskil handles:**

* Authorization server and consent management
* Token issuance and validation
* Compliance reporting and monitoring
* Data recipient onboarding
* CDR-compliant consent flow UI

**You build:**

* Resource Server with data endpoints
* Authentication between Fiskil and your systems
* Performant APIs with reliable data quality

***

Prerequisites [#prerequisites]

Before beginning your integration, ensure you have:

<AccordionGroup>
  <Accordion title="Fiskil Account & Provisioned Instances">
    You need access to Fiskil's platform with both Staging and Production instances provisioned. Each instance is isolated with separate keys, logs, and configuration.

    Contact Fiskil to provision your environments if you haven't already.
  </Accordion>

  <Accordion title="Understanding of CDR Obligations">
    As a CDR Data Holder, you have specific regulatory obligations beyond the technical integration. Review the [CDR FAQs](/data-holder/api-reference/cdr/cdr-faqs) to understand:

    * Your responsibilities as a Data Holder
    * Consumer rights and consent management
    * Dispute resolution requirements
    * Reporting obligations
    * Privacy safeguards
  </Accordion>

  <Accordion title="Technical Infrastructure">
    Your Resource Server will need:

    * HTTPS endpoints accessible by Fiskil
    * Infrastructure capable of meeting CDR performance and availability requirements
    * Monitoring and alerting systems
    * Stable customer and account identifier systems
  </Accordion>
</AccordionGroup>

***

Functional Requirements [#functional-requirements]

Resource Server Overview [#resource-server-overview]

Your Resource Server is an HTTPS API that Fiskil calls after a customer authorizes data sharing. It must:

* Accept and validate Bearer tokens issued by Fiskil
* Return data in CDR-compliant JSON format
* Implement proper error handling with standard HTTP status codes
* Support pagination for list endpoints

Authentication & Consent Flow Endpoints [#authentication--consent-flow-endpoints]

These endpoints are called during the user consent flow to identify customers and display their accounts.

<Cards>
  <Card title="Customer Search" href="/data-holder/api-reference/cdr/auth-customer-search">
    Look up a customer by email address or phone number during consent initiation.
  </Card>

  <Card title="Customer Accounts" href="/data-holder/api-reference/cdr/auth-customer-accounts">
    Return a list of accounts the customer can choose to share data from.
  </Card>

  <Card title="Customer Details" href="/data-holder/api-reference/cdr/auth-customer-details">
    Provide customer identity information for the consent flow.
  </Card>
</Cards>

<Callout type="warn">
  These endpoints are critical for the consent flow. They must return stable customer and account identifiers that never change.
</Callout>

CDR Data Endpoints [#cdr-data-endpoints]

After consent is granted, Fiskil calls your Resource Server to retrieve customer data. The specific endpoints you need to implement depend on your industry.

<Tabs items={["Banking", "Energy"]}>
  <Tab value="Banking">
    **Required endpoints:**

    | Category               | Endpoints                                                                                                     |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
    | **Accounts**           | Get Accounts, Get Account Detail                                                                              |
    | **Balances**           | Get Balances, Get Bulk Balances, Get Balances For Specific Accounts                                           |
    | **Transactions**       | Get Transactions For Account, Get Transaction Detail                                                          |
    | **Payees**             | Get Payees, Get Payee Detail                                                                                  |
    | **Direct Debits**      | Get Direct Debits For Account, Get Bulk Direct Debits, Get Direct Debits For Specific Accounts                |
    | **Scheduled Payments** | Get Scheduled Payments For Account, Get Scheduled Payments Bulk, Get Scheduled Payments For Specific Accounts |
    | **Instalment Plans**   | Get Instalment Plans For Account, Get Instalment Plans For Specific Accounts                                  |
  </Tab>

  <Tab value="Energy">
    **Required endpoints:**

    | Category           | Endpoints                                                                                                                  |
    | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
    | **Accounts**       | Get Energy Accounts, Get Energy Account Detail                                                                             |
    | **Balances**       | Get Balance For Energy Account, Get Bulk Balances, Get Balances For Specific Energy Accounts                               |
    | **Plans**          | Get Agreed Payment Schedule, Get Concessions                                                                               |
    | **Billing**        | Get Billing For Account, Get Bulk Billing, Get Billing For Specific Accounts                                               |
    | **Invoices**       | Get Invoices For Account, Get Bulk Invoices, Get Invoices For Specific Accounts                                            |
    | **Usage**          | Get Bulk Usage, Get Usage For Service Point, Get Usage For Specific Service Points                                         |
    | **Service Points** | Get Service Points, Get Service Point Detail, Get DER For Service Point, Get Bulk DER, Get DER For Specific Service Points |
  </Tab>
</Tabs>

API Standards & Patterns [#api-standards--patterns]

**Authentication**

Your Resource Server must validate Bearer tokens issued by Fiskil. See [Authentication](/data-holder/guides/build/jwt-security) for complete details on token validation and JWKS configuration.

```http
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Error Handling**

Return standard HTTP status codes and structured error responses. See [Error Handling](/data-holder/api-reference/cdr/errors) for complete specifications.

**Pagination**

Support pagination for list endpoints using `page` and `page-size` query parameters. Return `LinksPaginated` in responses.

***

Non-Functional Requirements [#non-functional-requirements]

These technical requirements are **mandatory for CDR compliance** and critical for integration success.

<Callout type="info">
  These requirements are mandated by CDR standards and monitored by regulators. Fiskil provides tooling to help you meet them, but your Resource Server must be designed with these constraints in mind.
</Callout>

Identity Stability [#identity-stability]

<Callout type="warn">
  **Critical Requirement:** Customer IDs and Account IDs must be permanent and stable. Changing these identifiers will break consents and violate CDR compliance.
</Callout>

**Customer IDs:**

* Must remain stable across all sessions and interactions
* Must be unique within your organization
* Must never be reused for different customers
* Must not encode temporary or session-specific information

**Account IDs:**

* Must remain stable over the lifetime of the account
* Must be unique within your organization
* Must persist even if the account is closed or reopened
* Must not change when account details are updated

**Impact of unstable IDs:**

* Active consents will break, requiring customers to re-authorize
* Data recipients will receive inconsistent data
* CDR compliance violations and potential regulatory action
* Poor customer experience and support burden

<Callout type="info">
  Use your system's internal primary keys or generate stable UUIDs. Avoid using account numbers or other customer-facing identifiers that might change.
</Callout>

Performance Requirements [#performance-requirements]

CDR mandates specific response time requirements measured at the **95th percentile** — meaning 95% of requests must respond within the specified time.

**Key Response Time Thresholds:**

| Priority          | Response Time | Example Endpoints                                  |
| ----------------- | ------------- | -------------------------------------------------- |
| **High Priority** | 1000ms        | Get Accounts, Get Energy Accounts, Get Customer    |
| **Low Priority**  | 1500ms        | Get Account Detail, Get Balances, Get Transactions |
| **Unattended**    | 4000ms        | Unattended calls to standard endpoints             |
| **Large Payload** | 6000ms        | Bulk Direct Debits, Bulk Billing                   |

<Callout type="info">
  These are mandatory CDR compliance requirements. Consistent failure to meet these thresholds will impact your regulatory standing.
</Callout>

For the complete breakdown of performance requirements by endpoint, see [Non-Functional Requirements](/data-holder/api-reference/cdr/cdr-nfrs). For how Fiskil Firewall protects your Resource Server from unbounded recipient load and abusive traffic, see [Firewall](/data-holder/guides/security/firewall).

Availability Requirements [#availability-requirements]

**Required Availability:** 99.5% per month (maximum 3.6 hours downtime)

Your Resource Server infrastructure must be designed for high availability:

* Implement redundancy and failover mechanisms
* Plan maintenance windows carefully to stay within limits
* Monitor uptime continuously
* Establish incident response procedures

<Callout type="info">
  Fiskil provides availability monitoring and alerting. Configure these tools during your initial setup to track your compliance with this requirement.
</Callout>

Data Quality Standards [#data-quality-standards]

<Callout type="warn">
  You must take reasonable steps to ensure CDR data is accurate, up-to-date, and complete (CDR Privacy Safeguard 11).
</Callout>

**Requirements:**

* Product data must be current and reflect your actual offerings
* Customer data must be synchronized with your source systems
* Historical data must be accurate and complete
* Data quality processes must be documented and auditable for regulatory review

<Callout type="info">
  For more information on data quality obligations, see the [OAIC's CDR Privacy Safeguard Guidelines](https://www.oaic.gov.au/consumer-data-right/cdr-privacy-safeguard-guidelines).
</Callout>

***

Implementation Checklist [#implementation-checklist]

Use this checklist to track your integration progress:

<Steps>
  <Step>
    Set up Resource Server infrastructure [#set-up-resource-server-infrastructure]

    Provision HTTPS endpoints accessible by Fiskil with appropriate scaling and redundancy for availability requirements.

    <Callout type="info">
      Start with your staging environment and validate before moving to production.
    </Callout>
  </Step>

  <Step>
    Implement consent flow endpoints [#implement-consent-flow-endpoints]

    Build the three required endpoints for the consent flow:

    * Customer Search (email/phone lookup)
    * Customer Accounts (list accounts for selection)
    * Customer Details (identity information)

    Ensure these endpoints return stable customer and account identifiers.
  </Step>

  <Step>
    Implement CDR data endpoints [#implement-cdr-data-endpoints]

    Build the required endpoints for your industry:

    * Banking: accounts, balances, transactions, payees, direct debits, scheduled payments
    * Energy: accounts, plans, billing, usage, service points, DER

    Start with core endpoints (accounts, balances) before adding others.
  </Step>

  <Step>
    Verify identifier stability [#verify-identifier-stability]

    Confirm that customer IDs and account IDs are permanent and stable:

    * Review your ID generation strategy
    * Test that IDs persist across sessions and system updates
    * Document your identifier scheme

    <Callout type="warn">
      This is critical — unstable IDs will break active consents and cause compliance issues.
    </Callout>
  </Step>

  <Step>
    Implement error handling [#implement-error-handling]

    Return proper HTTP status codes (403, 404, 422, 500) with structured error responses.

    Include `X-Sharing-Refused` header where required for CDR reporting.

    See [Error Handling](/data-holder/api-reference/cdr/errors) for specifications.
  </Step>

  <Step>
    Optimize for performance [#optimize-for-performance]

    Test and optimize to meet CDR performance requirements:

    * Measure response times at 95th percentile
    * Optimize database queries and caching
    * Implement appropriate timeouts
    * Load test at expected traffic levels

    Monitor high-priority endpoints (1000ms) and low-priority endpoints (1500ms) separately.
  </Step>

  <Step>
    Set up monitoring and alerting [#set-up-monitoring-and-alerting]

    Configure monitoring and alerting to track the 99.5% availability requirement:

    * Uptime monitoring
    * Response time metrics
    * Error rate tracking
    * Incident alerting

    <Callout type="info">
      Use Fiskil's telemetry tools to track these metrics. See [Logs](/data-holder/guides/telemetry/logs) and [Metrics](/data-holder/guides/telemetry/metrics).
    </Callout>
  </Step>

  <Step>
    End-to-end testing [#end-to-end-testing]

    Test the complete consent and data sharing flow:

    * Use Fiskil's testing tools to simulate real scenarios
    * Test all endpoints with various data scenarios
    * Validate error handling
    * Verify performance under load

    See [Testing & Compliance Tools](/data-holder/guides/testing/compliance-tools) for testing resources.
  </Step>

  <Step>
    Complete compliance validation [#complete-compliance-validation]

    Before going live, confirm:

    * All required endpoints are implemented and tested
    * Performance thresholds are consistently met
    * Availability monitoring is active and alerting
    * Error handling returns correct status codes and formats
    * Customer and account IDs are stable

    Work with Fiskil to complete any required regulatory certification or audit processes.
  </Step>
</Steps>

***

Resources & Next Steps [#resources--next-steps]

<Cards>
  <Card title="CDR FAQs" href="/data-holder/api-reference/cdr/cdr-faqs">
    Common questions about CDR implementation, compliance, and operations.
  </Card>

  <Card title="Non-Functional Requirements" href="/data-holder/api-reference/cdr/cdr-nfrs">
    Complete details on performance, availability, and traffic requirements.
  </Card>

  <Card title="Error Handling" href="/data-holder/api-reference/cdr/errors">
    Standard error codes and response formats for CDR Resource Servers.
  </Card>

  <Card title="Testing Tools" href="/data-holder/guides/testing/compliance-tools">
    Tools and resources for testing your CDR integration.
  </Card>

  <Card title="Getting Started Guide" href="/data-holder/guides/get-started/quickstart">
    Step-by-step tutorial for your first Fiskil integration.
  </Card>
</Cards>

Additional Resources [#additional-resources]

* [CDR Rules](https://www.legislation.gov.au/Details/F2020L00094) — Official Consumer Data Right legislation
* [Consumer Data Standards](https://consumerdatastandardsaustralia.github.io/standards/) — Technical standards and API specifications
* [ACCC CDR Guidance](https://www.accc.gov.au/by-business/consumer-data-right-cdr) — Compliance guide for Data Holders
* [OAIC Privacy Guidelines](https://www.oaic.gov.au/consumer-data-right/cdr-privacy-safeguard-guidelines) — Privacy safeguard requirements

***

Need Help? [#need-help]

<Callout type="info">
  Fiskil provides comprehensive support throughout your integration. Contact your account team or reach out through the [Fiskil Console](https://console.fiskil.com) for technical assistance.
</Callout>


---

# Legacy CDR Consent Flow APIs (/data-holder/api-reference/cdr-reference/legacy-auth)

Deprecated APIs to support CDR consent flow prior to 2026



If you onboarded to CDR Prior to 2026 you may have used different APIs to support the consent flow. You can continue to use these APIs to support the consent flow. If you want to migrate to the new Fiskil Consent Flow APIs let us know and we can work through the migration with you.

If you need to refer back to the legacy CDR consent flow APIs they are documented below:

Customer Search [#customer-search]

The customer search API structure is the same as described in the [API Reference](/data-holder/api-reference/cdr/auth-customer-search) however the endpoint was `POST /v1/common/customer/search`

```bash
$ curl --data '{"email": "hello@example.com"}' https://api.acme-corp.com.au/v1/common/customer/search
{
  "data": [
    {
      "id": "customerid",
      "name": "givenName familyName",
      "phoneNumber": "+6141234567890"
    }
  ]
}
```

Account Selection [#account-selection]

Account selection used the relevant "Get All Accounts" API for your industry.

* For [energy](/data-holder/api-reference/cdr/energy/get-energy-accounts) — `/v1/energy/customer/{customerId}/accounts`
* For [banking](/data-holder/api-reference/cdr/banking/get-accounts) — `/v1/banking/customer/{customerId}/accounts`

Customer Identity [#customer-identity]

Customer Identity data was fetched using the CDR [Customer Details API](/data-holder/api-reference/cdr/common/get-customer-detail)


---

# Fiskil FDX API (/data-holder/api-reference/fdx)

The Fiskil FDX API is a subset of the FDX API specification suited to most Open Finance use cases.



The Fiskil FDX API is a subset of the FDX API specification suited to most Open Finance use cases. You must implement this API and configure it as your Data Provider's Resource Server so your Data Provider can return the appropriate data once an authorisation has been created.

FDX Compliance [#fdx-compliance]

The Fiskil FDX API specifications represent a subset of the Financial Data Exchange (FDX) API specification. Using this specification (in whole or part) signifies your acceptance of the FDX API License Agreement, available at [https://financialdataexchange.org/](https://financialdataexchange.org/).

The FDX API specification is distributed exclusively by FDX. Removing required or conditional elements from the FDX API Certification Use Cases will result in non-conformant implementations. Please note that creating an FDX-compliant Data Provider API and allowing Fiskil to integrate with it constitutes acceptance of the FDX end user license agreement, available at [https://financialdataexchange.org/](https://financialdataexchange.org/). FDX distributes the complete API standard specification exclusively.


---

# Bring Your Own Data (/data-holder/api-reference/bring-your-own-data)

Share any commercial dataset through the Fiskil platform with secure, compliant data sharing infrastructure.



Fiskil enables you to share **custom commercial dataset** with third-party applications through our secure, compliant data sharing platform. Whether you have customer transaction data, IoT sensor readings, inventory systems, or proprietary business analytics, you can leverage Fiskil's infrastructure to monetize and distribute your data safely.

Implementation Process [#implementation-process]

Our team follows a proven methodology to get your data sharing solution live quickly:

<Steps>
  <Step>
    Discovery & Design [#discovery--design]

    Identify the datasets you want to share and design an OpenAPI specification with APIs and scopes.
  </Step>

  <Step>
    Build [#build]

    Build a Resource Server that implements the APIs from your specification.
  </Step>

  <Step>
    Deployment [#deployment]

    Upload your OpenAPI specification to the Fiskil Platform.
  </Step>

  <Step>
    Development & Testing [#development--testing]

    Use your staging environment to test an end-to-end data sharing scenario.
  </Step>

  <Step>
    Compliance Review [#compliance-review]

    Ensure all regulatory requirements are met and conduct security audits before go-live.
  </Step>

  <Step>
    Launch & Scale [#launch--scale]

    Deploy to production, onboard your first data consumers, and monitor performance as you scale.
  </Step>
</Steps>

What You Can Share [#what-you-can-share]

The Fiskil platform supports sharing virtually any type of structured commercial data:

* **Financial Services**: Transaction histories, account details, payment flows, credit scores
* **Energy & Utilities**: Usage patterns, billing data, meter readings, demand forecasting
* **Retail & E-commerce**: Purchase behavior, inventory levels, customer preferences
* **Healthcare**: Anonymized patient data, treatment outcomes, operational metrics
* **Real Estate**: Property valuations, market trends, rental histories
* **Transportation**: Fleet data, route optimization, fuel consumption, logistics
* **Manufacturing**: Supply chain data, production metrics, quality control
* **Agriculture**: Crop yields, weather patterns, soil conditions, livestock data

<Callout type="info">
  All data sharing follows your specified consent requirements and compliance
  frameworks, ensuring customer privacy and regulatory adherence.
</Callout>

Why Choose Fiskil [#why-choose-fiskil]

Built-in Compliance [#built-in-compliance]

* **Regulatory Ready**: Pre-configured for CDR, FDX, PSD2, and custom compliance frameworks
* **User Consent Management**: Granular permissions with clear audit trails

Enterprise Security [#enterprise-security]

* **FAPI 2.0 Authorization**: Highly secure version of OpenID Connect
* **Scoped Data Sharing**: Define scopes for your datasets to allow fine-grained access
* **Client Onboarding**: Use a centralised register for data recipients or use a selective developer program
* **Monitoring**: Real-time logging and alerting for all data access

Developer Experience [#developer-experience]

* **Rapid Integration**: Connect your existing APIs with minimal changes
* **Testing Tools**: Comprehensive sandbox environment for validation
* **Scalable Infrastructure**: Handles millions of API calls reliably

Getting Started [#getting-started]

Ready to share your commercial dataset through Fiskil? Our implementation team will work directly with you to design and deploy your custom data sharing solution.

<Cards>
  <Card icon={<DatabaseRestore />} title="Custom Data Solutions" description="Contact our implementation team to discuss your unique dataset and use case requirements. We'll help you design the optimal data sharing architecture." href="https://www.fiskil.com/contact">
    **Speak with Implementation Team**
  </Card>

  <Card icon={<Building />} title="Standard Finance APIs" description="Already have financial data? Check our pre-built Open Finance APIs for banking, payments, and lending data." href="/data-holder/api-reference/cdr-reference">
    **View Open Finance APIs**
  </Card>
</Cards>

Success Stories [#success-stories]

Companies across industries use Fiskil to unlock new revenue streams from their data:

* **Energy Retailers**: Share consumption patterns with smart home providers
* **Financial Institutions**: Enable fintech apps with transaction insights

<Callout type="success">
  Most integrations can be completed in 2-4 weeks, depending on data complexity
  and compliance requirements.
</Callout>

Next Steps [#next-steps]

<Card icon={<Phone />} title="Contact Implementation Team" description="Ready to get started? Schedule a consultation with our implementation team to discuss your custom data sharing requirements. We'll provide a detailed technical proposal and timeline." href="https://www.fiskil.com/contact" external={true} />

***

*Fiskil's platform is trusted by leading organizations to share billions of data points securely and compliantly. Let us help you turn your data into a strategic asset.*


---

# Integration Requirements (/data-holder/api-reference/latam-colombia/integration-requirements)

Complete functional and non-functional requirements for integrating with Fiskil's Colombian Open Finance Data Provider platform.



This document provides an overview of what you need to do to integrate with Fiskil's Data Provider platform and build a compliant Colombian Open Finance integration.

***

What You're Building [#what-youre-building]

When you integrate with Fiskil for the Colombian Open Finance standard, you're building a **Resource Server** — your API that exposes customer data according to Colombian regulatory requirements.

Responsibility Split [#responsibility-split]

**Fiskil handles:**

* Authorization server and consent management
* Token issuance and validation
* Compliance reporting and monitoring
* Data recipient onboarding
* Compliant consent flow UI

**You build:**

* Resource Server with data endpoints
* Authentication between Fiskil and your systems
* Performant APIs with reliable data quality

***

Prerequisites [#prerequisites]

Before beginning your integration, ensure you have:

<AccordionGroup>
  <Accordion title="Fiskil Account & Provisioned Instances">
    You need access to Fiskil's platform with both Staging and Production instances provisioned. Each instance is isolated with separate keys, logs, and configuration.

    Contact Fiskil to provision your environments if you haven't already.
  </Accordion>

  <Accordion title="Understanding of Colombian Open Finance Obligations">
    As a data provider under Colombia's Open Finance framework, you have specific regulatory obligations beyond the technical integration. Familiarize yourself with:

    * Your responsibilities as a data provider
    * Consumer rights and consent management under Ley 1581 de 2012 (Habeas Data)
    * Data sharing scope and limitations
    * Reporting and compliance obligations to the Superintendencia Financiera de Colombia
    * Privacy safeguards under Colombian data protection law
  </Accordion>

  <Accordion title="Technical Infrastructure">
    Your Resource Server will need:

    * HTTPS endpoints accessible by Fiskil
    * Infrastructure capable of meeting performance and availability requirements
    * Monitoring and alerting systems
    * Stable customer and account identifier systems (Cédula-based or internal IDs)
  </Accordion>
</AccordionGroup>

***

Functional Requirements [#functional-requirements]

Resource Server Overview [#resource-server-overview]

Your Resource Server is an HTTPS API that Fiskil calls after a customer authorizes data sharing. It must:

* Accept and validate Bearer tokens issued by Fiskil
* Return data in the expected JSON format
* Implement proper error handling with standard HTTP status codes
* Support pagination for list endpoints

Authentication & Consent Flow Endpoints [#authentication--consent-flow-endpoints]

These endpoints are called during the user consent flow to identify customers and display their accounts.

<Cards>
  <Card title="Customer Search" href="/data-holder/api-reference/latam-colombia/customerSearch">
    Look up a customer by email address during consent initiation.
  </Card>

  <Card title="Customer Accounts" href="/data-holder/api-reference/latam-colombia/listAccountsAuth">
    Return a list of accounts the customer can choose to share data from.
  </Card>

  <Card title="Customer Details" href="/data-holder/api-reference/latam-colombia/getIdentity">
    Provide customer identity information for the consent flow.
  </Card>
</Cards>

<Callout type="warn">
  These endpoints are critical for the consent flow. They must return stable customer and account identifiers that never change.
</Callout>

Colombian Open Finance Data Endpoints [#colombian-open-finance-data-endpoints]

After consent is granted, Fiskil calls your Resource Server to retrieve customer data. The `customer/{customerId}` path parameter is included by Fiskil in all requests to your server — third parties do not see this parameter.

**Required endpoints:**

| Category         | Endpoints                         |
| ---------------- | --------------------------------- |
| **Accounts**     | List Accounts, Get Account Detail |
| **Balances**     | Get Account Balance               |
| **Transactions** | List Account Transactions         |
| **Customers**    | Get Customer (Natural Person)     |

API Standards & Patterns [#api-standards--patterns]

**Authentication**

Your Resource Server must validate Bearer tokens issued by Fiskil. See [Authentication](/data-holder/guides/build/jwt-security) for complete details on token validation and JWKS configuration.

```http
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Customer ID Path Parameter**

All data sharing endpoints include `customer/{customerId}` in their path. Fiskil injects the correct customer ID based on the access token used to request the data. For example, your endpoint paths will look like:

* `/accounts/v1/customer/{customerId}/accounts`
* `/accounts/v1/customer/{customerId}/accounts/{accountID}/balance`
* `/accounts/v1/customer/{customerId}/accounts/{accountID}/transactions`
* `/customers/v1/customer/{customerId}/pn`

**Error Handling**

Return standard HTTP status codes and structured error responses:

* `401` — Unauthenticated (missing or invalid JWT)
* `403` — Forbidden (insufficient permissions)
* `404` — Not Found (resource does not exist)

**Pagination**

Support pagination for list endpoints using `page` and `pageSize` query parameters. Return pagination links and metadata in responses.

***

Non-Functional Requirements [#non-functional-requirements]

These technical requirements are critical for integration success.

<Callout type="info">
  Fiskil provides tooling to help you meet these requirements, but your Resource Server must be designed with these constraints in mind.
</Callout>

Identity Stability [#identity-stability]

<Callout type="warn">
  **Critical Requirement:** Customer IDs and Account IDs must be permanent and stable. Changing these identifiers will break consents and data sharing.
</Callout>

**Customer IDs:**

* Must remain stable across all sessions and interactions
* Must be unique within your organization
* Must never be reused for different customers
* Must not encode temporary or session-specific information

**Account IDs:**

* Must remain stable over the lifetime of the account
* Must be unique within your organization
* Must persist even if the account is closed or reopened
* Must not change when account details are updated

<Callout type="info">
  Use your system's internal primary keys or generate stable UUIDs. Avoid using account numbers or other customer-facing identifiers that might change.
</Callout>

Performance Requirements [#performance-requirements]

Your Resource Server should respond within reasonable time thresholds to ensure a good end-user experience.

**Recommended Response Time Thresholds:**

| Priority            | Response Time | Example Endpoints                       |
| ------------------- | ------------- | --------------------------------------- |
| **High Priority**   | 1000ms        | List Accounts, Get Customer             |
| **Standard**        | 1500ms        | Get Account Detail, Get Account Balance |
| **List Operations** | 2000ms        | List Account Transactions               |

Traffic Protection (Fiskil Firewall) [#traffic-protection-fiskil-firewall]

Fiskil Firewall sits in front of your Resource Server and automatically protects it from unbounded third-party load and abusive traffic:

* **Recipient throttling** — Fiskil’s default is **50 TPS** per data recipient. Excess calls are rejected (typically `429 Too Many Requests`) and are not forwarded to your Resource Server
* **DDoS mitigation** — volumetric and application-layer attacks are absorbed at the Fiskil edge
* **Malicious IP blocking** — abusive or known-malicious sources are blocked before they reach your systems

Open finance thresholds vary by market. Fiskil updates the Firewall configuration per environment to match the standards that apply to that deployment. For capacity planning details, see [Firewall](/data-holder/guides/security/firewall).

Availability Requirements [#availability-requirements]

**Recommended Availability:** 99.5% per month

Your Resource Server infrastructure should be designed for high availability:

* Implement redundancy and failover mechanisms
* Plan maintenance windows carefully
* Monitor uptime continuously
* Establish incident response procedures

Data Quality Standards [#data-quality-standards]

<Callout type="warn">
  You must take reasonable steps to ensure data is accurate, up-to-date, and complete.
</Callout>

**Requirements:**

* Account data must be current and reflect actual account state
* Customer data must be synchronized with your source systems
* Transaction and balance data must be accurate and complete
* Data quality processes must be documented

***

Implementation Checklist [#implementation-checklist]

Use this checklist to track your integration progress:

<Steps>
  <Step>
    Set up Resource Server infrastructure [#set-up-resource-server-infrastructure]

    Provision HTTPS endpoints accessible by Fiskil with appropriate scaling and redundancy.

    <Callout type="info">
      Start with your staging environment and validate before moving to production.
    </Callout>
  </Step>

  <Step>
    Implement consent flow endpoints [#implement-consent-flow-endpoints]

    Build the three required endpoints for the consent flow:

    * Customer Search (email lookup)
    * Customer Accounts (list accounts for selection)
    * Customer Details (identity information)

    Ensure these endpoints return stable customer and account identifiers.
  </Step>

  <Step>
    Implement data sharing endpoints [#implement-data-sharing-endpoints]

    Build the required data endpoints:

    * Accounts: List Accounts, Get Account Detail
    * Balances: Get Account Balance
    * Transactions: List Account Transactions
    * Customers: Get Customer (Natural Person)

    Start with accounts and balances before adding transactions and customer endpoints.
  </Step>

  <Step>
    Verify identifier stability [#verify-identifier-stability]

    Confirm that customer IDs and account IDs are permanent and stable:

    * Review your ID generation strategy
    * Test that IDs persist across sessions and system updates
    * Document your identifier scheme

    <Callout type="warn">
      This is critical — unstable IDs will break active consents and cause data sharing issues.
    </Callout>
  </Step>

  <Step>
    Implement error handling [#implement-error-handling]

    Return proper HTTP status codes (401, 403, 404) with structured error responses.
  </Step>

  <Step>
    Optimize for performance [#optimize-for-performance]

    Test and optimize to meet performance targets:

    * Measure response times at the 95th percentile
    * Optimize database queries and caching
    * Implement appropriate timeouts
    * Load test at expected traffic levels
  </Step>

  <Step>
    Set up monitoring and alerting [#set-up-monitoring-and-alerting]

    Configure monitoring to track availability and performance:

    * Uptime monitoring
    * Response time metrics
    * Error rate tracking
    * Incident alerting

    <Callout type="info">
      Use Fiskil's telemetry tools to track these metrics. See [Logs](/data-holder/guides/telemetry/logs) and [Metrics](/data-holder/guides/telemetry/metrics).
    </Callout>
  </Step>

  <Step>
    End-to-end testing [#end-to-end-testing]

    Test the complete consent and data sharing flow:

    * Use Fiskil's testing tools to simulate real scenarios
    * Test all endpoints with various data scenarios
    * Validate error handling
    * Verify performance under load

    See [Testing & Compliance Tools](/data-holder/guides/testing/compliance-tools) for testing resources.
  </Step>
</Steps>

***

Resources & Next Steps [#resources--next-steps]

<Cards>
  <Card title="Getting Started Guide" href="/data-holder/guides/get-started/quickstart">
    Step-by-step tutorial for your first Fiskil integration.
  </Card>

  <Card title="Authentication" href="/data-holder/guides/build/jwt-security">
    Complete details on token validation and JWKS configuration.
  </Card>

  <Card title="Testing Tools" href="/data-holder/guides/testing/compliance-tools">
    Tools and resources for testing your integration.
  </Card>
</Cards>

***

Need Help? [#need-help]

<Callout type="info">
  Fiskil provides comprehensive support throughout your integration. Contact your account team or reach out through the [Fiskil Console](https://console.fiskil.com) for technical assistance.
</Callout>


---

# Integration Requirements (/data-holder/api-reference/latam-chile/integration-requirements)

Complete functional and non-functional requirements for integrating with Fiskil's Chilean Open Finance Data Provider platform.



This document provides an overview of what you need to do to integrate with Fiskil's Data Provider platform and build a compliant Chilean Open Finance integration.

***

What You're Building [#what-youre-building]

When you integrate with Fiskil for the Chilean Open Finance standard, you're building a **Resource Server** — your API that exposes customer data according to Chilean regulatory requirements.

Responsibility Split [#responsibility-split]

**Fiskil handles:**

* Authorization server and consent management
* Token issuance and validation
* Compliance reporting and monitoring
* Data recipient onboarding
* Compliant consent flow UI

**You build:**

* Resource Server with data endpoints
* Authentication between Fiskil and your systems
* Performant APIs with reliable data quality

***

Prerequisites [#prerequisites]

Before beginning your integration, ensure you have:

<AccordionGroup>
  <Accordion title="Fiskil Account & Provisioned Instances">
    You need access to Fiskil's platform with both Staging and Production instances provisioned. Each instance is isolated with separate keys, logs, and configuration.

    Contact Fiskil to provision your environments if you haven't already.
  </Accordion>

  <Accordion title="Understanding of Chilean Open Finance Obligations">
    As a data provider under Chile's Open Finance framework, you have specific regulatory obligations beyond the technical integration. Familiarize yourself with:

    * Your responsibilities as a data provider
    * Consumer rights and consent management
    * Data sharing scope and limitations
    * Reporting and compliance obligations
    * Privacy safeguards under Chilean data protection law
  </Accordion>

  <Accordion title="Technical Infrastructure">
    Your Resource Server will need:

    * HTTPS endpoints accessible by Fiskil
    * Infrastructure capable of meeting performance and availability requirements
    * Monitoring and alerting systems
    * Stable customer and account identifier systems (RUT-based or internal IDs)
  </Accordion>
</AccordionGroup>

***

Functional Requirements [#functional-requirements]

Resource Server Overview [#resource-server-overview]

Your Resource Server is an HTTPS API that Fiskil calls after a customer authorizes data sharing. It must:

* Accept and validate Bearer tokens issued by Fiskil
* Return data in the expected JSON format
* Implement proper error handling with standard HTTP status codes
* Support pagination for list endpoints

Authentication & Consent Flow Endpoints [#authentication--consent-flow-endpoints]

These endpoints are called during the user consent flow to identify customers and display their accounts.

<Cards>
  <Card title="Customer Search" href="/data-holder/api-reference/latam-chile/customerSearch">
    Look up a customer by email address during consent initiation.
  </Card>

  <Card title="Customer Accounts" href="/data-holder/api-reference/latam-chile/listAccountsAuth">
    Return a list of accounts the customer can choose to share data from.
  </Card>

  <Card title="Customer Details" href="/data-holder/api-reference/latam-chile/getIdentity">
    Provide customer identity information for the consent flow.
  </Card>
</Cards>

<Callout type="warn">
  These endpoints are critical for the consent flow. They must return stable customer and account identifiers that never change.
</Callout>

Chilean Open Finance Data Endpoints [#chilean-open-finance-data-endpoints]

After consent is granted, Fiskil calls your Resource Server to retrieve customer data. The `customer/{customerId}` path parameter is included by Fiskil in all requests to your server — third parties do not see this parameter.

**Required endpoints:**

| Category         | Endpoints                         |
| ---------------- | --------------------------------- |
| **Accounts**     | List Accounts, Get Account Detail |
| **Balances**     | Get Account Balance               |
| **Transactions** | List Account Transactions         |
| **Customers**    | Get Customer (Natural Person)     |

API Standards & Patterns [#api-standards--patterns]

**Authentication**

Your Resource Server must validate Bearer tokens issued by Fiskil. See [Authentication](/data-holder/guides/build/jwt-security) for complete details on token validation and JWKS configuration.

```http
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Customer ID Path Parameter**

All data sharing endpoints include `customer/{customerId}` in their path. Fiskil injects the correct customer ID based on the access token used to request the data. For example, your endpoint paths will look like:

* `/accounts/v1/customer/{customerId}/accounts`
* `/accounts/v1/customer/{customerId}/accounts/{accountID}/balance`
* `/accounts/v1/customer/{customerId}/accounts/{accountID}/transactions`
* `/customers/v1/customer/{customerId}/pn`

**Error Handling**

Return standard HTTP status codes and structured error responses:

* `401` — Unauthenticated (missing or invalid JWT)
* `403` — Forbidden (insufficient permissions)
* `404` — Not Found (resource does not exist)

**Pagination**

Support pagination for list endpoints using `page` and `pageSize` query parameters. Return pagination links and metadata in responses.

***

Non-Functional Requirements [#non-functional-requirements]

These technical requirements are critical for integration success.

<Callout type="info">
  Fiskil provides tooling to help you meet these requirements, but your Resource Server must be designed with these constraints in mind.
</Callout>

Identity Stability [#identity-stability]

<Callout type="warn">
  **Critical Requirement:** Customer IDs and Account IDs must be permanent and stable. Changing these identifiers will break consents and data sharing.
</Callout>

**Customer IDs:**

* Must remain stable across all sessions and interactions
* Must be unique within your organization
* Must never be reused for different customers
* Must not encode temporary or session-specific information

**Account IDs:**

* Must remain stable over the lifetime of the account
* Must be unique within your organization
* Must persist even if the account is closed or reopened
* Must not change when account details are updated

<Callout type="info">
  Use your system's internal primary keys or generate stable UUIDs. Avoid using account numbers or other customer-facing identifiers that might change.
</Callout>

Performance Requirements [#performance-requirements]

Your Resource Server should respond within reasonable time thresholds to ensure a good end-user experience.

**Recommended Response Time Thresholds:**

| Priority            | Response Time | Example Endpoints                       |
| ------------------- | ------------- | --------------------------------------- |
| **High Priority**   | 1000ms        | List Accounts, Get Customer             |
| **Standard**        | 1500ms        | Get Account Detail, Get Account Balance |
| **List Operations** | 2000ms        | List Account Transactions               |

Traffic Protection (Fiskil Firewall) [#traffic-protection-fiskil-firewall]

Fiskil Firewall sits in front of your Resource Server and automatically protects it from unbounded third-party load and abusive traffic:

* **Recipient throttling** — Fiskil’s default is **50 TPS** per data recipient. Excess calls are rejected (typically `429 Too Many Requests`) and are not forwarded to your Resource Server
* **DDoS mitigation** — volumetric and application-layer attacks are absorbed at the Fiskil edge
* **Malicious IP blocking** — abusive or known-malicious sources are blocked before they reach your systems

Open finance thresholds vary by market. Fiskil updates the Firewall configuration per environment to match the standards that apply to that deployment. For capacity planning details, see [Firewall](/data-holder/guides/security/firewall).

Availability Requirements [#availability-requirements]

**Recommended Availability:** 99.5% per month

Your Resource Server infrastructure should be designed for high availability:

* Implement redundancy and failover mechanisms
* Plan maintenance windows carefully
* Monitor uptime continuously
* Establish incident response procedures

Data Quality Standards [#data-quality-standards]

<Callout type="warn">
  You must take reasonable steps to ensure data is accurate, up-to-date, and complete.
</Callout>

**Requirements:**

* Account data must be current and reflect actual account state
* Customer data must be synchronized with your source systems
* Transaction and balance data must be accurate and complete
* Data quality processes must be documented

***

Implementation Checklist [#implementation-checklist]

Use this checklist to track your integration progress:

<Steps>
  <Step>
    Set up Resource Server infrastructure [#set-up-resource-server-infrastructure]

    Provision HTTPS endpoints accessible by Fiskil with appropriate scaling and redundancy.

    <Callout type="info">
      Start with your staging environment and validate before moving to production.
    </Callout>
  </Step>

  <Step>
    Implement consent flow endpoints [#implement-consent-flow-endpoints]

    Build the three required endpoints for the consent flow:

    * Customer Search (email lookup)
    * Customer Accounts (list accounts for selection)
    * Customer Details (identity information)

    Ensure these endpoints return stable customer and account identifiers.
  </Step>

  <Step>
    Implement data sharing endpoints [#implement-data-sharing-endpoints]

    Build the required data endpoints:

    * Accounts: List Accounts, Get Account Detail
    * Balances: Get Account Balance
    * Transactions: List Account Transactions
    * Customers: Get Customer (Natural Person)

    Start with accounts and balances before adding transactions and customer endpoints.
  </Step>

  <Step>
    Verify identifier stability [#verify-identifier-stability]

    Confirm that customer IDs and account IDs are permanent and stable:

    * Review your ID generation strategy
    * Test that IDs persist across sessions and system updates
    * Document your identifier scheme

    <Callout type="warn">
      This is critical — unstable IDs will break active consents and cause data sharing issues.
    </Callout>
  </Step>

  <Step>
    Implement error handling [#implement-error-handling]

    Return proper HTTP status codes (401, 403, 404) with structured error responses.
  </Step>

  <Step>
    Optimize for performance [#optimize-for-performance]

    Test and optimize to meet performance targets:

    * Measure response times at the 95th percentile
    * Optimize database queries and caching
    * Implement appropriate timeouts
    * Load test at expected traffic levels
  </Step>

  <Step>
    Set up monitoring and alerting [#set-up-monitoring-and-alerting]

    Configure monitoring to track availability and performance:

    * Uptime monitoring
    * Response time metrics
    * Error rate tracking
    * Incident alerting

    <Callout type="info">
      Use Fiskil's telemetry tools to track these metrics. See [Logs](/data-holder/guides/telemetry/logs) and [Metrics](/data-holder/guides/telemetry/metrics).
    </Callout>
  </Step>

  <Step>
    End-to-end testing [#end-to-end-testing]

    Test the complete consent and data sharing flow:

    * Use Fiskil's testing tools to simulate real scenarios
    * Test all endpoints with various data scenarios
    * Validate error handling
    * Verify performance under load

    See [Testing & Compliance Tools](/data-holder/guides/testing/compliance-tools) for testing resources.
  </Step>
</Steps>

***

Resources & Next Steps [#resources--next-steps]

<Cards>
  <Card title="Getting Started Guide" href="/data-holder/guides/get-started/quickstart">
    Step-by-step tutorial for your first Fiskil integration.
  </Card>

  <Card title="Authentication" href="/data-holder/guides/build/jwt-security">
    Complete details on token validation and JWKS configuration.
  </Card>

  <Card title="Testing Tools" href="/data-holder/guides/testing/compliance-tools">
    Tools and resources for testing your integration.
  </Card>
</Cards>

***

Need Help? [#need-help]

<Callout type="info">
  Fiskil provides comprehensive support throughout your integration. Contact your account team or reach out through the [Fiskil Console](https://console.fiskil.com) for technical assistance.
</Callout>


---

# Consents (/data-holder/guides/build/consents)

Manage user consents and data access permissions



Fiskil manages the entire consent flow on your behalf — including authorization screens and an optional consumer consent dashboard. You focus on your product, while Fiskil provides a compliant, secure, and user-friendly consent experience.

With Fiskil, you do not need to design or implement consent screens yourself. Instead, you integrate with the hosted consent flow via OAuth2/OIDC. Fiskil then:

* Displays clear, compliant authorization screens
* Captures the user's consent (scopes, duration, accounts)
* Issues and validates tokens with the correct scopes
* Provides APIs and Console views for consent metadata
* Offers an optional consumer dashboard where end users can review or revoke consents

***

Consent Lifecycle [#consent-lifecycle]

Consents are treated as first-class records in Fiskil. The lifecycle includes:

* **Creation** — A user grants consent during the hosted authorization flow. Requested scopes, purpose, and duration are captured.
* **Activation** — Tokens are issued with the granted scopes.
* **Review** — Consent metadata, history, and associated API activity can be reviewed in the Console or via APIs.
* **Update** — If scopes or duration change, the consent record is updated and new tokens reflect the change.
* **Revocation/Expiry** — Users can withdraw consent at any time via the dashboard, or consents may expire automatically. Tokens are invalidated immediately.

***

What Fiskil Provides [#what-fiskil-provides]

* **Hosted consent screens** — Fully managed, OAuth/OIDC-compliant UI.
* **Consumer dashboard (optional)** — A hosted interface where users can view and revoke active consents.
* **Console & APIs** — For your teams to inspect consent metadata, history, and associated API calls.
* **Compliance built-in** — Consent flows follow global data sharing standards (e.g., CDR, FDX).

***

Integrating with the Consent Flow [#integrating-with-the-consent-flow]

1. Your app initiates OAuth2/OIDC with Fiskil.
2. The user is redirected to the hosted consent screen (branded with your logo and domain).
3. The user reviews the requested datasets, purposes, and duration.
4. The user approves consent; Fiskil records it and issues tokens with the correct scopes.
5. Your app receives the tokens and uses them to call your `Resource Server`.
6. Consent metadata is visible in the Console and accessible via APIs.

***

Branding and Configuration [#branding-and-configuration]

You can configure the consent experience without building it yourself:

* [**Branding**](/data-holder/guides/configure/branding) — Logo, name, colors
* [**Custom domain**](/data-holder/guides/configure/custom-domains) — e.g., `consent.yourcompany.com`

***

Compliance and UX Principles [#compliance-and-ux-principles]

Fiskil implements best practices into every consent flow so you don't need to build them yourself:

* **Clarity** — Show who is requesting access, what data will be shared, and for how long.
* **Least privilege** — Third parties request access to only the data they need by specifying scopes.
* **Revocability** — Clear withdrawal options during and after consent.
* **Trust** — Hosted on your branded domain, avoiding unnecessary third-party redirects.

***

Related [#related]

* [Authentication](/data-holder/guides/build/jwt-security)
* [Testing with Fiskil](/data-holder/guides/testing)
* [Security and Compliance](/data-holder/guides/security/sso)


---

# Authentication & Authorization (/data-holder/guides/build/end-user-authentication)

How your users authenticate and authorize data sharing.



The consent flow is made up of two parts: Authentication and Authorization. These are sometimes
referred to as AuthN and AuthZ.

**Authentication** is the process where a user identifies themselves.
**Authorization** is the process where a user determines which data is allowed to be shared and for how long.

You build APIs to allow Fiskil to authenticate your users and authorize data sharing

Authentication [#authentication]

POST /auth/v1/customer/search [#post-authv1customersearch]

[Reference](/data-holder/api-reference/cdr/auth-customer-search)

Fiskil has a built-in authentication system where end users must enter a One Time Passcode (OTP) sent to their
email or phone (via SMS) in order to authenticate. To facilitate this process your resource server must implement
a Customer Search endpoint.

Used to identify the customer associated with the authenticated session.

**Purpose:**
Look up a user based on their email address provided during authentication.

**Example response:**

```json
{
  "data": [
    {
      "id": "customerid",
      "name": "givenName familyName",
      "phoneNumber": "+6141234567890" // optional, for SMS OTP only
    }
  ]
}
```

GET /auth/v1/customer/{customerId} [#get-authv1customercustomerid]

[Reference](/data-holder/api-reference/cdr/auth-customer-details)

Once the customer is authenticated we also need some basic information about them to populate an [ID token](https://www.oauth.com/oauth2-servers/openid-connect/id-tokens/).
This is facilitated by the Customer Details endpoint.

Used to get customer identity details for issuing OpenID Connect ID Tokens.

**Example response:**

```json
{
  "id": "customerid",
  "email": "hello@example.com",
  "emailVerified": true,
  "familyName": "Sherman",
  "givenName": "Peter",
  "name": "Peter Sherman",
  "phoneNumber": "+15551234567",
  "phoneNumberVerified": true,
  "updatedAt": "2025-07-01T00:00:00Z",
  "address": {
    "streetAddress": "42 Wallaby Way",
    "locality": "Sydney",
    "region": "NSW",
    "postalCode": "2000",
    "country": "AUS"
  }
}
```

<Note>
  If you're [bringing your own identity provider](/data-holder/guides/configure/external-idp) you don't need to implement the Customer Search or Customer Details endpoints. Your IdP will handle authentication.
</Note>

Authorization [#authorization]

Once the end user is authenticated they must determine the terms of data sharing.

1. Accounts - which accounts data will be shared from
2. Scope - which datasets from the chosen accounts will be shared
3. Duration - how long the data will be shared for

The **Account List** endpoint is used to facilitate account selection. Scope and duration are determined by the
client when they make their authorization request.

GET /auth/v1/customer/{customerId}/accounts [#get-authv1customercustomeridaccounts]

[Reference](/data-holder/api-reference/cdr/auth-customer-accounts)

Used to list the accounts available to the customer during the consent.

**Example response:**

```json
{
  "accounts": [
    {
      "id": "acc_001",
      "name": "Jane's Savings",
      "type": "savings",
      "displayName": "Account A"
    },
    {
      "id": "acc_002",
      "name": "Joint Account",
      "type": "transaction",
      "displayName": "Account B"
    }
  ]
}
```


---

# JWT Security (/data-holder/guides/build/jwt-security)

JWT-based authentication between your Data Provider and Resource Server using JWKS and short-lived tokens.



The following steps provide a structured guide for integrating authentication with Fiskil's Data Provider platform.

Authentication Flow [#authentication-flow]

The diagram below illustrates how authentication works between the Fiskil Data Provider and your Resource Server:

<Mermaid
  chart="sequenceDiagram
    participant DR as Data Recipient
    participant DP as Fiskil Data Provider
    participant RS as Your Resource Server
    participant JWKS as JWKS Endpoint

    DR->>DP: Request data with consent
    DP->>DP: Generate JWT token
    Note over DP: Signs JWT with private key<br/>Includes aud, iss, sub claims

    DP->>RS: API request with JWT in Authorization header
    RS->>JWKS: Fetch public keys (if not cached)
    JWKS-->>RS: Return JWKS with public keys

    RS->>RS: Validate JWT signature
    RS->>RS: Validate claims (exp, aud, iss, sub, jti)

    alt JWT validation successful
        RS-->>DP: Return requested data
        DP-->>DR: Forward data to recipient
    else JWT validation failed
        RS-->>DP: Return 401 Unauthorized
        DP-->>DR: Return error response
    end"
/>

JWT [#jwt]

The Fiskil Data Provider uses [JSON Web Tokens (JWTs)](https://datatracker.ietf.org/doc/html/rfc7519) to authenticate to your Resource Server. JWTs are well-suited to Open Data platforms since they support fine-grained access control and short lifetimes. Requests to your API include a JWT in the `Authorization` header using the Bearer scheme.

Each JWT is signed by the Data Provider. The public keys are exposed via a JWKS endpoint (shared during onboarding). Tokens include a `kid` [JOSE header](https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.4) so your server can select the correct JWK.

The JWKS URL for your instance is available in the Console under **Settings → Domains**.

Validating the JWT [#validating-the-jwt]

Once you have the public key you must validate the JWT. When you validate the JWT, ensure that:

* The signature is valid.
* The token is not expired (check the `exp` claim).
* The `sub` and `iss` claims match your Data Provider subdomain (provided during onboarding).
* The `aud` is the URI of the resource being requested on the Data API.
* The `jti` has not been used before.

Node.js Implementation Example [#nodejs-implementation-example]

Here's a complete Node.js example showing how to validate JWTs from Fiskil's Data Provider:

```javascript
const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

// Configure JWKS client (replace with your actual JWKS URL)
const client = jwksClient({
  jwksUri: 'https://cdr.your-domain.com/.well-known/jwks.json',
  cache: true,
  cacheMaxAge: 3600000, // 1 hour
  rateLimit: true,
  jwksRequestsPerMinute: 5
});

// Store used JTIs to prevent replay attacks
const usedJtis = new Set();

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    if (err) {
      return callback(err);
    }
    const signingKey = key.getPublicKey();
    callback(null, signingKey);
  });
}

async function validateFiskilJWT(token, requestUrl, expectedIssuer) {
  try {
    // Verify and decode the JWT
    const decoded = jwt.verify(token, getKey, {
      algorithms: ['PS256', 'RS256'],
      issuer: expectedIssuer,
      audience: requestUrl,
      clockTolerance: 30 // Allow 30 second clock skew
    });

    // Additional validation checks
    const now = Math.floor(Date.now() / 1000);

    // Check token hasn't expired
    if (decoded.exp <= now) {
      throw new Error('Token has expired');
    }

    // Check subject matches issuer
    if (decoded.sub !== expectedIssuer) {
      throw new Error('Subject claim does not match expected issuer');
    }

    // Check for JTI replay attack
    if (usedJtis.has(decoded.jti)) {
      throw new Error('Token has already been used (replay attack)');
    }

    // Store JTI to prevent replay
    usedJtis.add(decoded.jti);

    // Clean up old JTIs periodically (implement based on your needs)
    // You might want to use Redis or another storage for production

    return {
      valid: true,
      claims: decoded
    };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

// Express.js middleware example
function authenticateJWT(req, res, next) {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing or invalid Authorization header' });
  }

  const token = authHeader.substring(7); // Remove 'Bearer ' prefix
  const requestUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
  const expectedIssuer = 'https://cdr.your-domain.com'; // Replace with your domain

  validateFiskilJWT(token, requestUrl, expectedIssuer)
    .then(result => {
      if (result.valid) {
        req.jwt = result.claims;
        next();
      } else {
        console.error('JWT validation failed:', result.error);
        res.status(401).json({ error: 'Invalid token' });
      }
    })
    .catch(error => {
      console.error('JWT validation error:', error);
      res.status(401).json({ error: 'Authentication failed' });
    });
}

// Usage in your Express route
app.get('/v1/energy/customer/:customerId/accounts', authenticateJWT, (req, res) => {
  // Access validated JWT claims via req.jwt
  console.log('Authenticated request from:', req.jwt.iss);
  console.log('Request ID:', req.jwt.jti);

  // Your API logic here
  res.json({ accounts: [] });
});
```

<Callout type="warning">
  This example stores used JTIs in memory. For production systems, use a distributed cache like Redis to prevent replay attacks across multiple server instances.
</Callout>

<Callout type="idea">
  Consider implementing JTI cleanup logic to remove expired entries and prevent memory leaks. You can use the `exp` claim to determine when to clean up each JTI.
</Callout>

Example: authenticated request [#example-authenticated-request]

The example below shows a JWT used to authenticate a request to a hypothetical utilities provider, **Acme Company**.

```http
GET /v1/energy/customer/bob/accounts HTTP/2
Host: data-api.acme-company.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVjZDdjMjEyLWM0YmQtNGRhNi04ZjhkLTgyNjUxODdiNDIwMCJ9.eyJpc3MiOiJodHRwczovL2Nkci5hY21lLWVuZXJneS5jb20iLCJzdWIiOiJodHRwczovL2Nkci5hY21lLWVuZXJneS5jb20iLCJhdWQiOiJodHRwczovL2RhdGEtYXBpLmFjbWU... (truncated)
```

<Callout type="info">
  For security and readability, avoid logging full tokens. Log only minimal metadata (for example, the jti).
</Callout>

Decoded JWT [#decoded-jwt]

Header [#header]

```json
{
  "alg": "PS256",
  "typ": "JWT",
  "kid": "ecd7c212-c4bd-4da6-8f8d-8265187b4200"
}
```

Claims [#claims]

```json
{
  "iss": "https://cdr.acme-company.com",
  "sub": "https://cdr.acme-company.com",
  "aud": "https://data-api.acme-company.com/v1/energy/customer/bob/accounts",
  "iat": 1691939022,
  "exp": 1692939022,
  "jti": "2e7da1da-e410-48ec-827f-e17658dd87b2"
}
```

JWT is a battle-tested specification for sharing cryptographically secured claims. Use a production-grade library to fetch JWKS and verify JWTs in your chosen programming language. For more information on JWT see the references below.

<Cards>
  <Card title="JWT.IO — JSON Web Tokens Introduction" href="https://jwt.io/introduction" icon={<DatabaseRestore />} />

  <Card title="JWT.IO — JSON Web Tokens Libraries" href="https://jwt.io/libraries" icon={<Building />} />
</Cards>

Firewall [#firewall]

While JWT is sufficient to authenticate the Data Provider with your API, we recommend adding a firewall IP allow-list to further protect your data.

* Fiskil provides IP addresses for allow-listing during onboarding.
* The IP addresses are also available in the Console under [**Settings → Resource Server**](https://console.fiskil.com/data-holder/settings/resource-server).

Final Notes [#final-notes]

Security is a complex topic and often a trade-off is being made between strictness and ease-of-use. If the above security mechanisms do not meet your expectations then please reach out to the Fiskil team and we can discuss alternative security schemes to ensure a smooth onboarding process while protecting your customers' sensitive information.


---

# Resource Server (/data-holder/guides/build/resource-server)

Responsibilities, contracts, and implementation guidance for a compliant Resource Server.



The Resource Server is your application's data API — responsible for exposing customer data after a user has given consent.

Fiskil handles authorization, token issuance, and consent orchestration. During the consent process and once a user has approved access, Fiskil calls your Resource Server with a JWT. Your job is to validate that token and return the right data.

***

How It Works [#how-it-works]

The diagram below illustrates the complete Resource Server integration flow:

<Mermaid
  chart="sequenceDiagram
    participant User as End User
    participant DR as Data Recipient
    participant DP as Fiskil Data Provider
    participant RS as Your Resource Server
    participant DB as Your Database

    User->>DR: Initiate data request
    DR->>DP: Request consent authorization
    DP->>User: Present consent screen
    User->>DP: Approve data sharing

    Note over DP: Generate JWT token<br/>based on approved permissions

    DP->>RS: API request with JWT
    RS->>RS: Validate JWT signature & claims
    RS->>RS: Check token vs endpoint requirements

    alt Valid token & sufficient
        RS->>DB: Query customer data
        DB-->>RS: Return requested data
        RS-->>DP: Return data (JSON)
        DP-->>DR: Forward data to recipient
        DR-->>User: Present data in application
    else Invalid token
        RS-->>DP: Return 401/403 error
        DP-->>DR: Return error response
        DR-->>User: Display error message
    end"
/>

Example Data Endpoint [#example-data-endpoint]

At least one endpoint that exposes real data is required to test and go live. The API must start with `/customer/{customerId}` so we fetch data for the customer who has granted the consent.

GET /customer/{customerId}/accounts/{id}/balances [#get-customercustomeridaccountsidbalances]

Returns the account balance.

**Example response:**

```json
{
  "account_id": "acc_001",
  "available": 1200.50,
  "current": 1250.75,
  "currency": "AUD"
}
```

You can return mock data during the initial testing phase.

***

Next Steps [#next-steps]

* [Review Fiskil Firewall & capacity limits](/data-holder/guides/security/firewall)
* [Implement Authentication & Authorization APIs](/data-holder/guides/build/end-user-authentication)
* [Set up your JWT validation](/data-holder/guides/build/jwt-security)
* [Register your Resource Server in the Console](/data-holder/guides/get-started/instances)
* [Review the go-live checklist](/data-holder/guides/go-live)


---

# Branding (/data-holder/guides/configure/branding)



Fiskil hosts the **consent authorization screens** and optional **consumer dashboard** on your behalf.
You can configure branding so customers interact with a trusted, familiar experience that reflects your organisation’s identity.

Branding is configured per instance in the [**Console → Settings → Branding**](https://console.fiskil.com/data-holder/settings/domains).

***

What You Can Brand [#what-you-can-brand]

You can edit the following elements for each instance:

* **Font** — choose typography that matches your brand.
* **Logos** — upload your organisation’s logo for use on consent flows and dashboards.
* **Brand Colors** — apply primary/secondary colors for buttons, highlights, and UI accents.
* **Business Identity Information** — display your organisation name and related identifiers.
* **Support Information** — provide customer support contact details (email, phone, link).
* **Policy Links** — link to your privacy policy, terms of service, or help center.
* …and more.

***

Consent Screens [#consent-screens]

All users complete their consent through the **Fiskil-hosted consent flow**.
Branding ensures these screens feel consistent with your product experience.

The consent flow always displays:

* The **Data Recipient** requesting access
* The **scopes and datasets** requested
* The **duration** of access
* Your configured logo, font, and brand colors
* Any **support or policy links** you provide

***

Consumer Dashboard (Optional) [#consumer-dashboard-optional]

If enabled, Fiskil provides an **end-user dashboard** where customers can:

* View their active consents
* Revoke consents at any time

Your branding applies here as well:

* Logo and display name
* Font and brand colors
* Custom domain

***

Best Practices [#best-practices]

* Clearly distinguish your **Staging** and **Production** branding to reduce chances of using the wrong instance.
* Use a **custom domain** for production instances (e.g., `consent.acme.com`).
* Provide clear, accessible **support information** and **policy links** to build trust.
* Use high-resolution assets for logos and icons to ensure accessibility.

***

Related [#related]

* [Custom Domain](/data-holder/guides/configure/custom-domains)
* [Consent](/data-holder/guides/build/consents)
* [Instances](/data-holder/guides/get-started/instances)


---

# Custom Domains (/data-holder/guides/configure/custom-domains)



You can configure a **custom domain** for your Data Provider instance so that customers interact with a familiar branded domain (e.g., `consent.acme-corp.com`).

This domain will be used for:

* Hosted consent authorization screens
* Optional consumer consent dashboard
* API endpoints (HTTPS and optional mTLS)
* Outgoing email (for OTPs and notifications)

<Info>
  You can always view the active domain for your Data Provider in the [Console → Settings → Domains](https://console.fiskil.com/data-holder/settings/domains).
</Info>

***

Adding a Custom Domain [#adding-a-custom-domain]

Configure domains in the Console under **Custom Domains**.

<Steps>
  <Step>
    Click 

    **Add Domain**
  </Step>

  <Step>
    Enter the desired subdomain (e.g., 

    `cdr.acme-corp.com.au`

    ). It must be a subdomain of your organisation’s root domain.
  </Step>

  <Step>
    Click 

    **Next**
  </Step>

  <Step>
    Create the required DNS records as shown in Console
  </Step>

  <Step>
    Click 

    **Start Verification**
  </Step>
</Steps>

* If DNS records verify successfully, Fiskil will provision TLS certificates and update your instance.
* Propagation may take time; track progress in the Console.
* Once a domain is configured, it cannot be changed without assistance. If you need to reset, [contact support](https://fiskil.atlassian.net/servicedesk/customer/portal/6/group/23/create/55?summary=Change+custom+domain).

You can configure **separate custom domains** for staging and production. Switch between environments using the drop-down in the top-right of the Custom Domains menu.

***

Required DNS Records [#required-dns-records]

When enabling a custom domain, multiple DNS records must be created:

1. Endpoint Records (CNAME) [#1-endpoint-records-cname]

* CNAME records map your custom domain to the Fiskil-assigned subdomains.
* Required for:
  * HTTPS API endpoints
  * mTLS API endpoints
  * Consent authorization UI
  * Consent dashboard

***

2. CAA Records (TLS Certificates) [#2-caa-records-tls-certificates]

* Two CAA records are required so Fiskil can use Google and Let’s Encrypt to provision TLS certificates.
* Ensures browsers trust your custom domain.

***

3. Email Records (Authentication) [#3-email-records-authentication]

Fiskil sends emails from your Data Provider domain (e.g., for OTPs and notifications).
To ensure deliverability, configure:

* **DKIM & SPF** —
  * `CNAME` records for `em***.<custom-domain>`
  * `s1._domainkey.<custom-domain>`
  * `s2._domainkey.<custom-domain>`

* **DMARC** —
  * `TXT` record for `_dmarc.<custom-domain>`
  * Defines a DMARC policy to reject unauthenticated messages

Together, these records allow public email servers to verify messages sent from your domain, reducing the risk of spoofing and improving inbox delivery.

***

Best Practices [#best-practices]

* Use separate subdomains for **staging** and **production** (e.g., `consent.staging.acme-corp.com`, `consent.acme-corp.com`).
* Configure DNS records early — verification requires propagation and may take hours.
* Apply strict DMARC policies (`p=reject`) for production domains.

***

Related [#related]

* [Configure Overview](/data-holder/guides/configure)
* [Branding & Consent Screen](/data-holder/guides/configure/branding)
* [Instances](/data-holder/guides/get-started/instances)


---

# External Identity Providers (/data-holder/guides/configure/external-idp)

Learn how to bring your own identity provider into your Fiskil environment



If you already have an Identity Provider (IdP) and it supports OpenID Connect (OIDC) then you can integrate
it with Fiskil to provide the same, robust authentication standards as you do in other applications.

<Note>
  It is optional to configure an external Identity Provider. Fiskil can use a [built-in](/data-holder/guides/build/end-user-authentication#authentication) authentication experience
  facilitated by your resource server.
</Note>

Integrating an IdP with Fiskil means the [authentication](/data-holder/guides/build/end-user-authentication#authentication)
step is managed by your IdP. You don't need to build Customer Search or Customer Details endpoints on your resource
server. This saves you time and ensures a consistent authentication experience for your users.

<Warning>
  If you operate within a regulated open data ecosystem such as CDR, be sure to confirm your IdP can comply with
  the authentication standards of the ecosystem.
</Warning>

Connecting Your IdP to Fiskil [#connecting-your-idp-to-fiskil]

Setting up your IdP with Fiskil involves adding Fiskil as an OIDC client for your IdP.

1. Add Fiskil as a client with your IdP
2. Share the client credentials with Fiskil
3. Provide the Authorization and Token endpoints for your IdP to Fiskil
4. Enable external IdP for your instance (contact us for this step)

Limitations [#limitations]

* Fiskil only works with OpenID Connect for federated identity. Your IdP must support it.
* The ID Token returned by your IdP must contain a `sub` claim that is **unique** and **stable** for the authenticated user. It must not change between consents.
* The `sub` claim in the ID token must work as an ID to look up user data for the authenticated user. It will be used as the `{customerId}` path parameter in requests to your resource server.

If you have any questions about whether we can support your IdP please reach out to us and we can discuss this with you.


---

# Overview (/data-holder/guides/configure)



After you’ve built and tested your Resource Server, the next step is to configure your **instances** for production readiness.

Configuration is managed per instance in the **Fiskil Console**. Each instance (staging or production) has its own settings for domains, branding, security, and optional compliance profiles.

***

What You Can Configure [#what-you-can-configure]

* **Custom Domains**
  Use your own DNS name (e.g., `consent.yourcompany.com`) for hosted consent flows.
  See: [Custom Domain](/docs/configure/custom-domains)

* **Branding**
  Control how consent screens and dashboards are presented to your customers with your logo and display name.
  See: [Branding & Consent Screen](/docs/configure/branding)

* **Resource Server Settings**
  Define the base URL, JWKS validation, optional mTLS, and firewall allow-lists.
  See: [Resource Server Settings](/docs/configure/resource-server-settings)

* **Compliance Profiles** (optional)
  Apply pre-configured scopes, headers, and behaviors aligned with standards such as CDR or FDX.

***

Where Configuration Happens [#where-configuration-happens]

All configuration is available in the **Console → Instance Settings**.

Each instance has:

* Its own **domains** (staging vs production)
* Its own **keys and secrets**
* Its own **logs and metrics**

***

Best Practices [#best-practices]

* **Separate environments** — Keep staging and production instances isolated with their own DNS, keys, and secrets.
* **Migrate safely** — Test configuration changes in staging before applying them to production.
* **Lock down production** — Use strict firewall allow-lists, DNS validation, and change control for live traffic.

***

Related [#related]

* [Instances](/data-holder/guides/get-started/instances)
* [Custom Domain](/data-holder/guides/configure/custom-domains)
* [Branding & Consent Screen](/data-holder/guides/configure/branding)
* [Resource Server Settings](/data-holder/guides/configure/resource-server-settings)


---

# Onboarding Clients (/data-holder/guides/configure/onboarding-clients)

Invite third parties to integrate with your Data Provider



Once you are ready to bring in third party developers you will need to register them as Clients with your Data Provider. How you do this depends
on the industry and jurisdiction you operate in.

* **CDR**: Client onboarding is done through the [OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591). Any accredited
  data recipient can register directly with your Data Provider instance over API.
* **FDX**: FDX client onboarding is managed through Plaid. By adding Plaid as a client you gain access to their vast network of partners.
* **Other**: If you are running a plain FAPI 2.0 Data Provider in another jurisdiction you must onboard clients manually in the Fiskil Console

Onboarding clients in the Fiskil Console [#onboarding-clients-in-the-fiskil-console]

If you operate a plain FAPI 2.0 Data Provider you'll need to manually add clients in the [Fiskil Console](https://console.fiskil.com/data-holder/settings/client-registration).
There are two steps to this process.

Registering the client [#registering-the-client]

FAPI 2.0 Data Providers use the `private_key_jwt` [OIDC Client Authentication method](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.9). This is one of
the methods accepted by the FAPI 2.0 standard. Clients must pre-register a public key that can be used to verify JWT assertions they make as part of client authentication. Follow
the steps below from the [Client Registration](https://console.fiskil.com/data-holder/settings/client-registration) menu.

1. Click "Add New Client"
2. Fill out the form
   * **Client Name**: A human-readable name for the client. This will be presented to your users during the consent flow
   * **JWKS URI** The clients JWKS URI. Must be HTTPS. This URL points to the public key the client uses for Private Key JWT Client Authentication and pushed authorization request objects
   * **Brand Image** A logo for the client. This will be presented to end users during the consent flow.
3. Confirm by clicking "Add Client"

Issuing client certificates [#issuing-client-certificates]

FAPI 2.0 Data Providers use mTLS as an additional transport security measure and as a mechanism for supporting sender-constrained access tokens
as defined in [RFC 8705](https://www.rfc-editor.org/info/rfc8705/). The mTLS certificates are issued by Fiskil's private FAPI 2.0 certificate authority.
The steps to get a mTLS client certificate for a new client are:

1. Ask your client to send you a Certificate Signing Request (CSR) from your client in PEM encoded DER format
2. On the [Client Registration](https://console.fiskil.com/data-holder/settings/client-registration) menu, find the client in the table
3. Click the **Actions** menu for the client's row and select "Manage Certificates"
4. Click **Create Certificate** in the newly opened dialog
5. Paste the CSR in the text area and click **Create**
6. Copy the **Certificate** and the **Certificate Chain** from the result dialog and send both to your client. Note they only need to present the leaf certificate
   in order to establish a connection with your Data Provider's mTLS endpoint

<Note>
  If your client needs assistance generating a CSR, they can use the below snippet to create a CSR and private key in one:

  ```bash
  openssl req -new -newkey rsa:2048 -keyout client.key -sha256 -subj "/CN=My New Client" -out client.csr -nodes
  ```

  Have them send `client.csr` to you. Make sure they keep the `client.key` file private and save it somewhere safe as this is the private key they must use with the issued certificate
</Note>


---

# Resource Server Settings (/data-holder/guides/configure/resource-server-settings)



Each Data Provider instance must be linked to a **Resource Server** — your API that exposes customer and product data.

Configuration is managed in the [**Console → Settings → Resource Server**](https://console.fiskil.com/data-holder/settings/resource-server).
Settings are applied per instance (staging, production, or additional environments).

***

What You Configure [#what-you-configure]

* **Base URL**
  The public HTTPS URL of your Resource Server. This must be accessible from Fiskil.

* **JWKS URL**
  The JWKS endpoint used to validate Fiskil [Authentication](/data-holder/guides/build/jwt-security) JWTs.
  * You retrieve your isntance's public key from this URL

* **Firewall Allow-Lists (optional)**
  Restrict inbound traffic to requests originating from Fiskil IPs visible in the Resource Server menu.

***

Best Practices [#best-practices]

* Always use **distinct Resource Server URLs** for staging and production.
* Use firewall allow-lists for production environments.

***

Related [#related]

* [Instances](/data-holder/guides/get-started/instances)
* [Build Overview](/data-holder/guides/build/resource-server)
* [Authentication](/data-holder/guides/build/jwt-security)


---

# Instances (/data-holder/guides/get-started/instances)

Deploy and manage Data Provider instances for your environments.



An **instance** is a deployed Data Provider with its own configuration, DNS, keys, and operational logs. Instances are fully isolated — each has separate secrets, JWKS keys, audit logs, and request logs.

***

Staging vs Production [#staging-vs-production]

Every instance is tagged as either `staging` or `production`.

* **Staging**
  * Flexible environment with Testing tools
  * Supports mock recipients and easier iteration
  * Relaxed change controls

* **Production**
  * Customer-facing and compliance-critical
  * Strict change control and audit requirements
  * Hardened security posture

***

What You Configure Per Instance [#what-you-configure-per-instance]

Each instance can be configured independently:

* **Domains** — Custom DNS (see [Custom Domain](/data-holder/guides/configure/custom-domains))
* **Branding** — Logo, display name, and consent screen identity (see [Branding](/data-holder/guides/configure/branding))
* **Resource Server settings** — Base URL, JWT validation (JWKS), optional mTLS
* **Compliance profile** (optional) — Pre-configured scopes, headers, and behaviors for standards such as CDR or FDX

***

Typical Lifecycle [#typical-lifecycle]

1. Your instances are deployed by Fiskil when you onboard.
2. Integrate your Resource Server with the **staging** instance and validate using Testing tools.
3. Connect your finalised resource server to the **production** instance with locked-down DNS, secrets, and alerting.
4. Promote changes from staging → production using versioned, scheduled releases.

<Callout type="info">
  Migrate changes through Staging before Production. Keep DNS, keys, and secrets distinct for each instance.
</Callout>


---

# Quickstart (/data-holder/guides/get-started/quickstart)

Ship your first Data Provider integration — from resource server to end-to-end validation — in under an hour.



Ship your first Data Provider integration — from resource server to end-to-end validation — in under an hour.

**Estimated time**: 30–60 minutes

***

Before You Begin [#before-you-begin]

To follow this guide, you'll need:

* Access to the Fiskil Console with org admin permissions
* A domain you control (for DNS/branding setup)
* An engineer to implement or mock your Resource Server

***

Step 1 — Provision your environments [#step-1--provision-your-environments]

Once you've been approved for the Fiskil Data Provider platform, we will provision separate Staging and Production instances for you.

Each instance is isolated and includes:

* Environment-specific keys
* Separate logs and metrics
* Testing and sandbox tools

Use Staging for all initial development and integration.

***

Step 2 — Implement a Minimal Resource Server [#step-2--implement-a-minimal-resource-server]

Your Resource Server is your API — Fiskil will call it after a user gives consent.

For your first integration, you'll need to implement these three endpoints:

Required Endpoints [#required-endpoints]

| Endpoint                                                      | Purpose                                       | Reference                                                     |
| ------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
| `GET /auth/v1/customer/search`                                | Identify the customer during the consent flow | [Link](/data-holder/api-reference/cdr/auth-customer-search)   |
| `GET /auth/v1/customer/{customerId}/accounts`                 | List accounts available for sharing           | [Link](/data-holder/api-reference/cdr/auth-customer-accounts) |
| `GET /auth/v1/customer/{customerId}`                          | Get customer identity information             | [Link](/data-holder/api-reference/cdr/auth-customer-details)  |
| `GET /v1/customer/{customerId}/accounts/{accountId}/balances` | Example data endpoint to expose customer data |                                                               |

These endpoints must:

* Be accessible by the Fiskil Data Provider over HTTPS
* Accept Bearer tokens and validate them using Fiskil's JWKS

<Callout type="info">
  For initial testing, these endpoints can return static or mock data.
</Callout>

Example: Balances Endpoint [#example-balances-endpoint]

```bash
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
  https://<your-resource-server>/v1/customer/{customerId}/accounts/{account_id}/balances
```

Example response:

```json
{
  "account_id": "acc_001",
  "available": 1200.50,
  "current": 1250.75,
  "currency": "AUD"
}
```

Step 3 — Link Your Resource Server [#step-3--link-your-resource-server]

In the [Console](https://console.fiskil.com/data-holder/settings/resource-server):

* Set the base URL for your Resource Server in the `staging` instance
* *(Optional)* Configure an allowlist to restrict inbound traffic to Fiskil IPs
* Confirm your API is reachable and healthy

***

Step 4 — Configure Branding & DNS (Optional) [#step-4--configure-branding--dns-optional]

[Customize](https://console.fiskil.com/data-holder/branding) your user-facing consent flow with:

* Your logo and display name
* A custom domain, like `consent.yourcompany.com`

To configure this, see: [Custom Domain Setup](/data-holder/guides/configure/custom-domains)

***

Step 5 — Run an End-to-End Test [#step-5--run-an-end-to-end-test]

Use Fiskil's Testing tools to validate the full consent flow.

As part of your onboarding we will invite you to our testing tools. The testing tools depend on the kind of integration you're building, whether it operates within a regulatory standard or you're a voluntary data provider.

***

Step 6 — Go Further [#step-6--go-further]

Once you've validated your integration:

* Add full support for additional endpoints and scopes
* Apply a compliance profile (e.g., CDR, FDX)
* Enable logs and metrics. See [Logs](/data-holder/guides/telemetry/logs) and [Metrics](/data-holder/guides/telemetry/metrics)

***

Step 7 — Go Live [#step-7--go-live]

To launch in production:

* Complete any required regulator certification or validation (if applicable)
* Register and onboard trusted third-party clients (e.g., Plaid, energy apps)
* Point production integrations to your live instance

***

Core Concepts Recap [#core-concepts-recap]

**Instance**: An isolated environment with its own domain, keys, logs, and configuration.

**Resource Server**: Your API — it exposes customer data and responds to Fiskil using standard contracts.

**Scopes & Consent**: Your customers must consent to sharing data. The scope of that consent defines what data can be shared. Fiskil manages Scopes and Consents.

**Compliance Profile**: A preset behavior template (headers, scopes, APIs) based on standards like CDR or FDX.


---

# Frequently Asked Questions (/data-holder/guides/help/faq)

Common questions about Fiskil Data Provider implementation and usage.



General Questions [#general-questions]

What is Fiskil Data Provider? [#what-is-fiskil-data-provider]

Fiskil Data Provider is a platform that enables secure, compliant data sharing between financial institutions and authorized third parties. It handles consent management, token validation, and API orchestration while maintaining regulatory compliance.

How does Fiskil ensure data security? [#how-does-fiskil-ensure-data-security]

Fiskil implements multiple layers of security including OAuth 2.0/OIDC authentication, JWT token validation, optional mTLS, and comprehensive audit logging. All data transmission is encrypted and access is strictly controlled through consent-based scopes.

What compliance frameworks does Fiskil support? [#what-compliance-frameworks-does-fiskil-support]

Fiskil supports various regulatory frameworks including CDR (Consumer Data Right), FDX (Financial Data Exchange), and PSD2. Compliance profiles can be configured per instance to ensure adherence to specific regulatory requirements.

Technical Questions [#technical-questions]

How do I integrate my Resource Server with Fiskil? [#how-do-i-integrate-my-resource-server-with-fiskil]

Integration involves configuring your Resource Server settings in the Fiskil Console, implementing JWT token validation, and ensuring your API endpoints enforce the appropriate scopes. See our [Getting Started](/data-holder/guides/get-started/quickstart) guide for detailed steps.

Can I use custom domains for my Data Provider? [#can-i-use-custom-domains-for-my-data-provider]

Yes, Fiskil supports custom domains for consent screens, APIs, and consumer dashboards. This ensures a seamless, branded experience for your customers. See [Custom Domains](/data-holder/guides/configure/custom-domains) for setup instructions.

How do I test my integration before going live? [#how-do-i-test-my-integration-before-going-live]

Fiskil provides comprehensive testing tools including Postman collections, request logs, metrics dashboards, and compliance validation tools. Always test thoroughly in staging before promoting to production. See [Testing](/data-holder/guides/testing) for more details.

Support [#support]

For additional questions or technical support, please [contact our team](https://www.fiskil.com/contact).


---

# Go Live Checklist (/data-holder/guides/go-live)

Complete guide to validate your Data Provider is ready for production, including compliance requirements and data recipient onboarding.



Going live means more than creating a production instance — it includes onboarding **Data Recipients** and, if applicable, meeting regulatory obligations.

This comprehensive checklist covers **technical readiness**, **operational preparedness**, and **regulatory compliance** to ensure a smooth production deployment.

***

Understanding Responsibilities [#understanding-responsibilities]

Before diving into the checklist, it's important to understand what Fiskil manages versus your responsibilities.

<Tabs items={["What Fiskil Handles", "Your Responsibilities"]}>
  <Tab value="What Fiskil Handles">
    * Secure, standards-compliant data disclosure
    * Consent management flows and optional consumer dashboard
    * Authentication and authorization services (OIDC, scopes, tokens)
    * [Fiskil Firewall](/data-holder/guides/security/firewall): recipient throttling, DDoS mitigation, and malicious IP protection
    * Operational logging, audit trails, and retention
  </Tab>

  <Tab value="Your Responsibilities">
    * Customer support, dispute resolution, and complaints handling
    * Publishing a **Data Sharing Policy** (or equivalent, if required by your regime)
    * Internal compliance practices (governance, risk management, training)
    * Coordinating with regulators, integrators, or registries where applicable
  </Tab>
</Tabs>

<Info>
  See our [FAQ section](/data-holder/guides/help/faq) for detailed information on compliance responsibilities.
</Info>

***

Pre-Go Live Checklist [#pre-go-live-checklist]

Complete these steps before onboarding Data Recipients to ensure your Data Provider is production-ready.

<Steps>
  <Step title="Technical Preconditions">
    Ensure your Resource Server meets all technical requirements:

    * [ ] Resource Server implemented and tested in **staging**
    * [ ] Authentication validated: JWT signatures checked, `aud`/`iss` claims enforced
    * [ ] Error model and pagination consistent with Fiskil standards
  </Step>

  <Step title="Production Instance Setup">
    Configure your production environment:

    * [ ] Production instance created in Console
    * [ ] Custom domain configured and DNS propagated
    * [ ] Branding and policies reviewed in Console
  </Step>

  <Step title="End-to-End Testing">
    Validate all systems work together correctly:

    * [ ] End-to-end consent flows validated in **staging** (consent creation, token issuance, API calls)
    * [ ] Evidence captured (logs, screenshots) for audit purposes
    * [ ] Request Logs reviewed in Console; Log Drains configured if using external SIEM
    * [ ] Metrics reviewed for latency, error rates, and throughput under test load
  </Step>

  <Step title="Operational Readiness">
    Ensure your team is prepared to support production operations:

    * [ ] Monitoring and alerting configured on Logs and Metrics (if forwarding to external tools)
    * [ ] Teams trained on accessing Logs and Metrics in the Console
    * [ ] Procedures established for responding to Data Recipient support requests
    * [ ] Escalation processes defined for internal issues or Fiskil support
  </Step>

  <Step title="Compliance & Regulatory Validation">
    Complete required compliance steps for your market:

    * [ ] Conformance tests completed for your compliance profile (e.g., CDR, FDX)
    * [ ] Redirect URIs registered and verified for both staging and production
    * [ ] Regulatory approval or certification completed (if required)

    <Warning>
      If you are not going live with a compliance profile but require regulatory onboarding, [contact the Fiskil team](https://fiskil.com/contact) for support with validation and registry/integrator requirements.
    </Warning>
  </Step>
</Steps>

***

Go Live Process [#go-live-process]

Once you've completed the pre-go live checklist, follow these steps to onboard Data Recipients and monitor your production deployment.

<Steps>
  <Step title="Onboard Data Recipients">
    Begin integrating with trusted recipients:

    * Add trusted Data Recipients in the Console (direct integrations or registry-approved apps)
    * Validate consent flows and data exchange with each recipient
    * Start with a small number of recipients to monitor system behavior

    <Tip>
      Begin with **trusted Data Recipients** you've worked with during testing to ensure smooth initial deployments.
    </Tip>
  </Step>

  <Step title="Monitor Initial Traffic">
    Closely observe your first production data exchanges:

    * Monitor first production traffic in Logs and Metrics to confirm stable operation

    * Watch for any unexpected error patterns or performance issues

    * Validate that all consent flows work as expected in production

    * [ ] First production traffic successfully processed with stable metrics
  </Step>

  <Step title="Scale Recipient Onboarding">
    Gradually expand your recipient network:

    * Continue onboarding additional Data Recipients as confidence grows
    * Maintain monitoring and support processes as volume increases
    * Document any lessons learned for future onboardings
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Regulatory Onboarding (If Applicable)">
    If your market requires specific regulatory or registry onboarding:

    * Work with Fiskil to complete regulator or registry onboarding (e.g., ACCC in Australia)
    * Provide evidence of conformance testing where required
    * Coordinate timelines with your compliance team and Fiskil support
    * Validate your Resource Server against relevant API standards (e.g., CDR, FDX)
    * Capture test evidence (logs, metrics, error handling) for regulatory review
  </Accordion>

  <Accordion title="Troubleshooting Go Live Issues">
    Common issues and solutions during go live:

    * **DNS propagation delays**: Allow 24-48 hours for DNS changes to fully propagate
    * **Certificate validation**: Ensure TLS certificates are properly configured and not expired
    * **Recipient integration failures**: Review logs for authentication or scope issues
    * **Performance concerns**: Monitor metrics and adjust instance resources if needed
  </Accordion>
</AccordionGroup>

<Note>
  Your instance is technically live once created in production. The final milestone is **successfully onboarding Data Recipients** and confirming stable traffic patterns.
</Note>


---

# AEMO (/data-holder/guides/integrations/aemo)

Connect with AEMO as a Secondary Data Holder for energy data sharing through Fiskil's managed integration.



Fiskil provides a fully managed integration with AEMO (Australian Energy Market Operator) as the Secondary Data Holder for sharing electricity data. This includes usage, DER (Distributed Energy Resources), and service point data access through Consumer Data Right (CDR) compliant APIs.

***

What's Included [#whats-included]

<CardGroup cols={2}>
  <Card title="Energy Data Access" icon="bolt">
    Secure access to electricity usage, DER data, and service point information through AEMO's Secondary Data Holder services.
  </Card>

  <Card title="Managed Credentials" icon="shield-check">
    Automated credential management with password rotation, health checks, and expiry notifications built-in.
  </Card>
</CardGroup>

Key Features [#key-features]

* **Automated setup** — Pre-configured integration ready for your energy data sharing needs
* **Credential management** — Built-in password rotation and health monitoring
* **CDR compliance** — Fully compliant with Consumer Data Right regulations
* **Real-time monitoring** — Live status updates and automated alerts

***

Getting Started [#getting-started]

<Info>
  AEMO integration is available as a managed service through Fiskil. Our team will handle the technical setup and ongoing maintenance for you.
</Info>

Ready to enable AEMO integration for your energy data sharing? Contact our support team to get started:

<Card title="Contact Support" href="https://fiskil.atlassian.net/servicedesk/customer/portal/6" icon="headset">
  Reach out to our team to enable AEMO integration for your Fiskil Data Provider instance.
</Card>

***

What Our Team Provides [#what-our-team-provides]

<Steps>
  <Step title="Integration Setup">
    Complete configuration of AEMO connectivity with your Fiskil Data Provider instance.
  </Step>

  <Step title="Credential Management">
    Automated password rotation, health checks, and monitoring for uninterrupted service.
  </Step>

  <Step title="Ongoing Support">
    Continuous monitoring, maintenance, and technical support for your AEMO integration.
  </Step>
</Steps>

***

Configuring your AEMO credentials [#configuring-your-aemo-credentials]

AEMO user passwords are valid for 90 days. After this period, the password must be reset. To minimise the risk of downtime during rotations, we strongly recommend maintaining two active AEMO users with the required access:

<Warning>
  If only one user exists, requests may fail between resetting the password in the AEMO portal and updating it in the Fiskil Console
</Warning>

By alternating between two users, you can avoid this issue. When one user’s credentials are due to expire, switch to the other before performing a reset.

Both users must be granted read access to the CDR - Energy API access entity in AEMO.

Setting Up AEMO Users for the First Time [#setting-up-aemo-users-for-the-first-time]

To connect with AEMO through Fiskil, you’ll need to create two AEMO users with the appropriate permissions. This setup allows you to rotate credentials without service interruptions and helps prevent downtime when passwords expire.

1. Create your first user via the AEMO MSATs portal.
2. Grant the first user read access to CDR - Energy API access.
3. Create your second user.
4. Grant the second user the same read access.
5. Go to the [AEMO menu](https://console.fiskil.com/data-holder/settings/integrations) in the Data Provider Console.
6. Click the AEMO card.
7. Enter the username and password for the first user.

<Note>
  When you update your credentials in the Fiskil Console, we automatically perform a connectivity health check by pinging AEMO with the new credentials. If it fails, your credentials won't be updated.
</Note>

Updating AEMO Integration During Password Rotation [#updating-aemo-integration-during-password-rotation]

When one of your AEMO users’ credentials is close to expiry, follow these steps to switch to the second user and update the credentials in the Fiskil Console. This ensures continuous connectivity with AEMO and avoids any API downtime.

1. Reset the password for the second user in the AEMO portal.
2. Go to the [AEMO menu](https://console.fiskil.com/data-holder/settings/integrations) in the Data Provider Console.
3. Enter the second user's updated credentials.

Repeat this process when the next user is due for password expiry. Alternating users ensures uninterrupted data sharing through AEMO.

Credential Expiry Details [#credential-expiry-details]

The expiry date shown in the console is an estimated expiry calculated as 90 days from the time the credential was last updated. This may appear incorrect if your credential was created earlier but only updated in the Fiskil Console more recently.

If the console shows a future date, it reflects when you last updated the credential in Fiskil — not necessarily when it was rotated in AEMO.

Multiple AEMO Participants [#multiple-aemo-participants]

If your brand uses multiple Participant IDs (PIDs), configure a separate username and password for each PID:

1. Click Advanced in the AEMO configuration menu.
2. Enter the participant ID, username, and password.
3. Click Add Another Participant if needed and repeat step 2.
4. Click Save.

Apply the same two-user rotation strategy to each participant to avoid downtime. We will remind you to update your credentials every 90 days.

Pre-Production Credentials [#pre-production-credentials]

Currently, this credential rotation feature is for production environments only. Fiskil will continue to manage pre-production AEMO credential rotations on your behalf. If this changes, we'll notify you in advance.

Notifications [#notifications]

Fiskil sends password expiry reminders via email to your designated technical contact.

The first email is sent 10 days before the estimated expiry date.
Reminders will continue until the credentials are updated in the Fiskil Console.
Ensure your Technical Contact is correctly set in the Console under [Settings > Company Information](https://console.fiskil.com).

References [#references]

* [AEMO Guide to CDR APIs](https://aemo.com.au/-/media/files/initiatives/cdr/guide-to-cdr-apis.pdf?la=en)
* [AEMO Guide to User Rights Management](https://aemo.com.au/-/media/files/market-it-systems/guide-to-user-rights-management.pdf)

***

Related Documentation [#related-documentation]

<CardGroup cols={2}>
  <Card title="Energy CDR API Reference" href="/api-reference/energy-cdr-overview" icon="bolt">
    Technical specifications for Energy CDR endpoints and data schemas.
  </Card>

  <Card title="Console Settings" href="/data-holder/guides/configure" icon="gear">
    Learn more about configuring integrations and managing your instance.
  </Card>
</CardGroup>


---

# Gentrack (/data-holder/guides/integrations/gentrack)

Connect with Gentrack utility platforms through Fiskil for compliant energy and utility data sharing.



Fiskil offers a seamless integration with Gentrack, a leading provider of customer management and billing solutions for energy and utility companies. Enable secure, consented access to customer data and utility information while maintaining full compliance with industry regulations.

***

What's Available [#whats-available]

<CardGroup cols={2}>
  <Card title="Customer Data Access" icon="users">
    Access customer information, billing data, usage patterns, and service configurations through Gentrack's platform.
  </Card>

  <Card title="Compliance Ready" icon="shield-check">
    Built-in compliance with Consumer Data Right (CDR) and utility data sharing regulations with automated governance.
  </Card>
</CardGroup>

Supported Data Types [#supported-data-types]

* **Customer information** — Account profiles, service addresses, and contact details
* **Billing and payment data** — Invoice history, payment records, and account balances
* **Utility usage data** — Consumption patterns, meter readings, and service usage
* **Service configurations** — Connection details, tariff information, and service parameters

***

Getting Started [#getting-started]

<Info>
  Gentrack integration requires coordination between Fiskil, Gentrack, and your technical teams. Our specialists will guide you through the entire process.
</Info>

Ready to connect your Gentrack platform with Fiskil? Contact our team to begin the integration process:

<CardGroup cols={2}>
  <Card title="Contact Integration Team" href="https://www.fiskil.com/contact" icon="rocket">
    Schedule a consultation to discuss your Gentrack integration requirements and objectives.
  </Card>

  <Card title="Email Support" href="mailto:support@fiskil.com" icon="envelope">
    Send details about your Gentrack environment and integration goals to our technical team.
  </Card>
</CardGroup>

***

How It Works [#how-it-works]

Fiskil uses Gentrack's native APIs to facilitate data sharing. Simply provide your client ID and secret to Fiskil and we can connect to your Velocity environment.

If you want more information on how the integration works we are happy to chat with you and your Gentrack account manager.

<Warning>
  If you need to support CDR Complex Accounts you may need to review your Velocity role mappings
</Warning>

***

What We Provide [#what-we-provide]

<Steps>
  <Step title="Integration Setup">
    Complete configuration of secure API endpoints, consent management, and monitoring infrastructure.
  </Step>

  <Step title="Testing & Go-Live">
    Comprehensive testing, validation, and ongoing support to ensure reliable operation.
  </Step>
</Steps>

<Note>
  Integration timeline is typically 6-12 weeks depending on platform complexity and customization requirements.
</Note>

***

Additional Resources [#additional-resources]

<CardGroup cols={2}>
  <Card title="Energy CDR Reference" href="/api-reference/energy-cdr-overview" icon="lightning-bolt">
    Technical specifications for Energy Consumer Data Right standards and implementations.
  </Card>

  <Card title="Instance Configuration" href="/data-holder/guides/configure" icon="cog">
    Learn how to configure and optimize your Fiskil Data Provider for utility integrations.
  </Card>
</CardGroup>


---

# Plaid (/data-holder/guides/integrations/plaid)

Connect with Plaid, the leading US financial data aggregator, through Fiskil Data Provider for secure financial data sharing.



Fiskil offers a comprehensive integration with Plaid, the leading US-based financial data aggregator. Connect securely with thousands of financial institutions to enable account aggregation, transaction analysis, and identity verification while maintaining full control over user consent and authorization flows.

***

What's Available [#whats-available]

<CardGroup cols={2}>
  <Card title="Financial Data Access" icon="building-columns">
    Secure access to account data, transaction history, identity verification, and income data from thousands of US financial institutions.
  </Card>

  <Card title="Enhanced Security" icon="shield-check">
    FAPI 2.0-compliant authorization layer with unified consent management and comprehensive monitoring through Fiskil's platform.
  </Card>
</CardGroup>

Key Use Cases [#key-use-cases]

* **Account aggregation** — Access multiple bank accounts and financial institutions
* **Transaction analysis** — Retrieve detailed transaction history and categorization
* **Income verification** — Verify user income for lending and financial services
* **Identity confirmation** — Validate user identity against bank records

***

Getting Started [#getting-started]

<Info>
  Plaid integration through Fiskil requires coordination with our technical team to ensure proper configuration, testing, and compliance setup.
</Info>

Ready to integrate Plaid with your Fiskil Data Provider? Contact our team to begin the process:

<CardGroup cols={2}>
  <Card title="Schedule Integration Call" href="https://www.fiskil.com/contact" icon="calendar">
    Book a consultation to discuss your Plaid integration requirements and timeline.
  </Card>

  <Card title="Email Our Team" href="mailto:support@fiskil.com" icon="envelope">
    Send details about your use case and expected data requirements to our support team.
  </Card>
</CardGroup>

***

What We Provide [#what-we-provide]

<Steps>
  <Step title="Integration Planning">
    Review your specific requirements and plan the integration architecture with proper security measures.
  </Step>

  <Step title="Implementation & Testing">
    Complete setup of endpoints, consent flows, and comprehensive testing of security and performance.
  </Step>

  <Step title="Go Live Support">
    Production deployment with monitoring, documentation, and ongoing support for your team.
  </Step>
</Steps>

<Note>
  Plaid integration setup typically takes 2-4 weeks depending on complexity and testing requirements.
</Note>

***

Related Documentation [#related-documentation]

<CardGroup cols={2}>
  <Card title="FDX API Reference" href="/api-reference/fdx-overview" icon="book">
    Learn about FDX standards and API specifications for financial data sharing.
  </Card>

  <Card title="Getting Started Guide" href="/data-holder/guides/get-started/quickstart" icon="play">
    Set up your Fiskil Data Provider instance and basic configuration.
  </Card>
</CardGroup>


---

# Tally Group (/data-holder/guides/integrations/tally-group)

Integrate with Tally Group's energy billing platforms through Fiskil for secure customer and billing data sharing.



Fiskil provides a comprehensive integration with Tally Group, the leading provider of customer and billing platforms used by energy retailers across Australia and New Zealand. Enable secure, consented access to customer data and billing information while maintaining full compliance with energy data sharing regulations.

***

What's Available [#whats-available]

<CardGroup cols={2}>
  <Card title="Energy Data Access" icon="bolt">
    Access customer account information, billing data, usage patterns, and service point data through Tally Group's platform.
  </Card>

  <Card title="Compliance Ready" icon="shield-check">
    Built-in compliance with Consumer Data Right (CDR) and energy data sharing regulations with automated consent management.
  </Card>
</CardGroup>

Key Data Types [#key-data-types]

* **Customer account information** — Account details, service addresses, and customer profiles
* **Billing data** — Historical bills, payment information, and billing cycles
* **Usage data** — Energy consumption patterns and meter readings
* **Service point data** — Connection details and service configurations

***

Getting Started [#getting-started]

<Info>
  Tally Group integration requires close collaboration between Fiskil, Tally Group, and your technical teams to ensure proper configuration and compliance.
</Info>

Ready to connect your Tally Group platform with Fiskil? Contact our team to begin the integration process:

<CardGroup cols={2}>
  <Card title="Schedule Discovery Call" href="https://www.fiskil.com/contact" icon="phone">
    Book a consultation to discuss your integration requirements and data sharing objectives.
  </Card>

  <Card title="Email Integration Team" href="mailto:support@fiskil.com" icon="envelope">
    Send details about your current Tally Group setup and integration goals.
  </Card>
</CardGroup>

***

What We Provide [#what-we-provide]

<Steps>
  <Step title="Technical Planning">
    Assessment of your Tally Group configuration and design of data sharing architecture with security measures.
  </Step>

  <Step title="Implementation & Testing">
    Complete setup of secure endpoints, consent workflows, and comprehensive testing for reliability and compliance.
  </Step>

  <Step title="Go Live Support">
    Production deployment with monitoring, team training, and ongoing maintenance and optimization.
  </Step>
</Steps>

<Note>
  Integration timeline is typically 4-8 weeks depending on complexity and requirements.
</Note>

***

Related Documentation [#related-documentation]

<CardGroup cols={2}>
  <Card title="Energy CDR Overview" href="/api-reference/energy-cdr-overview" icon="zap">
    Learn about Energy Consumer Data Right standards and API specifications.
  </Card>

  <Card title="Configure Your Instance" href="/data-holder/guides/configure" icon="settings">
    Set up and configure your Fiskil Data Provider for energy data sharing.
  </Card>
</CardGroup>


---

# Introduction to Data Provider (/data-holder/guides/introduction)

Enable secure, user-permissioned data sharing with confidence. Fiskil handles authorization, consent flows, and compliance so you can focus on your product.



Fiskil Data Provider enables your application to expose first-party data to trusted third parties with confidence. We take care of OpenID Connect authorization, user consent flows, multi-environment support, and operational tooling so your team can focus on your product and user experience.

<Cards>
  <Card title="Start Building" href="/data-holder/guides/get-started/quickstart" icon={<DatabaseRestore />} />
</Cards>

<Callout type="info">
  Fiskil is certified for SOC 2 Type 2 and ASAE 3150 Type 2. We offer integrated DDoS protection, secure audit trails, and industry-aligned safeguards. Learn more in our [product overview](https://www.fiskil.com/product/data-provider).
</Callout>

***

What is User-Permissioned Data Sharing? [#what-is-user-permissioned-data-sharing]

**User-Permissioned Data Sharing** is a model where your customers are in control. They explicitly grant consent for trusted third parties (Data Recipients) to access specific datasets, for a defined purpose and duration.

Unlike traditional data sharing models — bulk exports, file transfers, or backchannel APIs — user-permissioned data sharing is:

* **Consent-driven** — Users approve access via hosted consent flows
* **Scoped** — Access tokens carry only the permissions granted by the user
* **Time-bound** — Consents expire automatically or can be revoked at any time
* **Auditable** — All activity is logged and linked to a consent record

This model is the foundation of the Fiskil Data Provider. It enables you to expose first-party data securely and compliantly, without building complex authorization and consent infrastructure yourself.

***

What is the Fiskil Data Provider? [#what-is-the-fiskil-data-provider]

The **Fiskil Data Provider** is the platform that turns your organization into a **trusted source of user-permissioned data**.

You are the Data Provider: you own the customer and product data. Fiskil gives you everything you need to expose that data securely, with built-in consent, authorization, and compliance.

Your Core Responsibilities [#your-core-responsibilities]

As a Data Provider, you:

* Implement the **Resource Server** — APIs that return customer and product data
* Define the **datasets and scopes** that can be shared

What Fiskil Provides [#what-fiskil-provides]

Fiskil handles the infrastructure:

* Hosts the **consent flows and dashboards** on your branded domain
* Issues and validates tokens aligned to the granted scopes
* Provides the **management console, request logs, and metrics** for your team
* Handles the heavy lifting of compliance (authorization standards, audit trails, regulatory reporting)

Why Choose Fiskil? [#why-choose-fiskil]

* **Accelerated time to market** — Ship data sharing in weeks, not years
* **Security built-in** — Tokens, JWKS validation, audit logs, DDoS protection
* **User experience managed for you** — Hosted consent screens and optional consumer dashboard
* **Global standards ready** — Designed for frameworks like CDR, FDX, and open banking

***

Architecture Overview [#architecture-overview]

The Fiskil Data Provider works alongside your **Resource Server** to deliver secure, user-permissioned data sharing. Here's how the components connect and who is responsible for each:

Core Components [#core-components]

<Tabs items={["Your Resource Server", "Fiskil Data Provider", "Data Recipients"]}>
  <Tab value="Your Resource Server">
    * Your API that implements the data-sharing endpoints (e.g., accounts, balances, transactions)
    * Authenticates the Fiskil Data provider to secure your connection
    * Returns customer and product data in the expected format
  </Tab>

  <Tab value="Fiskil Data Provider">
    * Authorization server for consent flows and token issuance
    * Hosted consent UI and optional consumer consent dashboard
    * Instance management (staging, production, multi-region/brand)
    * Authentication (JWT, JWKS, optional mTLS)
    * Logs and metrics for observability
  </Tab>

  <Tab value="Data Recipients">
    * Trusted third-party apps or services requesting access
    * Integrated directly (custom) or via regulatory registries (e.g., accredited recipients)
    * Use OAuth2/OIDC flows to obtain tokens scoped by user consent
  </Tab>
</Tabs>

How It Works [#how-it-works]

<Steps>
  <Step title="Consent Initiation">
    A Data Recipient initiates a consent flow with your customer.
  </Step>

  <Step title="User Authentication & Consent">
    Fiskil's Data Provider authorization server authenticates the user, presents branded consent screens, and captures approved scopes.
  </Step>

  <Step title="Token Issuance">
    Fiskil issues an access token with the specific scopes granted by the user.
  </Step>

  <Step title="Data Access">
    The Data Recipient calls Fiskil data sharing endpoints with the token to access consented data.
  </Step>

  <Step title="Authorization & Response">
    Fiskil validates the token and checks that the request is authorised before fetching the customer data from your Resource Server.
  </Step>

  <Step title="Monitoring & Compliance">
    All activity is logged in Request Logs and surfaced in Metrics for monitoring and audit purposes.
  </Step>
</Steps>

Division of Responsibilities [#division-of-responsibilities]

<Cards>
  <Card title="You (Data Provider)" icon={<DatabaseRestore />}>
    Build and maintain your Resource Server.
  </Card>

  <Card title="Fiskil" icon={<Building />}>
    Provide the Data Provider infrastructure: consent flows, tokens, AuthN/AuthZ, observability, and compliance-ready tooling.
  </Card>

  <Card title="Data Recipients" icon={<Phone />}>
    Build integrations with your data under user consent.
  </Card>
</Cards>

***

How Fiskil Fits Into Your Architecture [#how-fiskil-fits-into-your-architecture]

* Your team builds and manages a `Resource Server`, which implements the APIs to expose your data
* Fiskil provides:
  * A FAPI 2.0-compliant authorization & resource server
  * Fully managed consent flows
  * Staging and production environments
  * A management console for observability, configuration, and tooling
* Third parties access data through direct onboarding or via registered data recipient frameworks (e.g., CDR, FDX)

Environments [#environments]

Each integration runs in isolated **instances**:

* **Staging**: for development, integration, and testing with mock recipients
* **Production**: for live, regulated traffic
* Additional instances can be created for multi-brand or multi-region deployments

<Callout type="idea">
  Learn more about setting up your environments in our [Instances Guide](/data-holder/guides/get-started/instances).
</Callout>

***

Key Capabilities [#key-capabilities]

Financial-grade Authorization [#financial-grade-authorization]

Certified FAPI 2.0 OpenID Connect implementation, providing robust protection for sensitive data.

Consent Management [#consent-management]

A complete system to create, view, and revoke user consents via API or prebuilt UI components.

Observability and Auditability [#observability-and-auditability]

Real-time traffic logs, availability metrics, and audit trails for complete visibility into data sharing activities.

Third-party Onboarding [#third-party-onboarding]

Onboard external recipients directly or integrate with regulatory data sharing registers.

Complex Account Support [#complex-account-support]

Support for organisational, joint, and multi-party accounts with flexible permission management.

Global Data Sharing Standards [#global-data-sharing-standards]

Support for frameworks such as Consumer Data Right (CDR) and Financial Data Exchange (FDX).

Product and Metadata Sharing [#product-and-metadata-sharing]

Expose product schemas and metadata alongside customer-specific data.

Regulatory Reporting [#regulatory-reporting]

Workflows aligned with compliance and reporting obligations for your jurisdiction.

***

Get Started [#get-started]

Choose how you'd like to begin your integration:

<Cards>
  <Card title="Deploy Your First Tenant" href="/data-holder/guides/get-started/instances" icon={<DatabaseRestore />}>
    Set up staging and production environments for your data sharing integration.
  </Card>

  <Card title="Build Your Resource Server" href="/data-holder/guides/build/resource-server" icon={<Building />}>
    Implement the APIs that will expose your customer and product data.
  </Card>

  <Card title="Follow a Regulatory Framework" href="/data-holder/guides/integrations/plaid" icon={<Phone />}>
    Integrate with established frameworks like CDR, FDX, or open banking standards.
  </Card>
</Cards>

***

Stay Connected [#stay-connected]

<Cards>
  <Card title="Read Our Blog" href="https://www.fiskil.com/blog" icon={<DatabaseRestore />}>
    Stay updated with the latest insights and best practices in data sharing.
  </Card>

  <Card title="Subscribe to Our Newsletter" href="https://www.fiskil.com/newsletter" icon={<Phone />}>
    Get product updates and industry news delivered to your inbox.
  </Card>
</Cards>


---

# Compliance Tools (/data-holder/guides/testing/compliance-tools)

Support for validating regulated Data Provider instances against conformance requirements.



If your Data Provider instance is operating under a **compliance profile** (e.g., CDR, FDX, open banking), additional validation may be required before going live.

Compliance validation ensures that:

* All required endpoints are implemented correctly
* Responses align with mandated schemas and headers
* Consent flows meet regulatory expectations
* Metrics and reporting obligations can be demonstrated

***

How Fiskil Helps [#how-fiskil-helps]

When compliance requirements apply, Fiskil can support you in:

* **Validating endpoints** against regulatory conformance test requirements
* **Preparing for registry onboarding** (e.g., Accredited Data Recipient registries)
* **Working with integrators or market operators** to confirm compatibility
* **Troubleshooting errors** uncovered during compliance validation

***

Requesting Support [#requesting-support]

Compliance validation tools and processes vary by framework.
Please [contact the Fiskil team](https://fiskil.com/contact) to:

* Discuss the compliance framework you are operating under
* Understand what validation and conformance tests are required
* Access additional testing tools where available
* Coordinate with Fiskil to complete certification or registry onboarding

<Note>
  If your instance does not use a compliance profile, you do not need to run regulatory validation.
  Functional testing with [Postman](/data-holder/guides/testing/postman) and [Request Logs](/data-holder/guides/telemetry/logs) is sufficient.
</Note>

***

Example Coverage Areas [#example-coverage-areas]

During compliance validation, you may need to demonstrate:

* Customer and account discovery endpoints
* Consent lifecycle behavior (create, review, revoke)
* Error codes and error handling
* Performance and availability thresholds
* Reporting metrics

***

***

Related [#related]

* [Metrics](/data-holder/guides/telemetry/metrics)
* [Go Live Checklist](/data-holder/guides/go-live)


---

# Overview (/data-holder/guides/testing)

How to test and validate your Fiskil Data Provider integration before going live.



Before moving to production, every integration must be **tested and validated**.
Fiskil provides tools to help you check both **functional correctness** (your Resource Server works as expected) and **compliance alignment** (if a regulatory framework applies).

***

What You Can Test [#what-you-can-test]

* **Authorization flows** — confirm that users can successfully grant and revoke consent.
* **Token validation** — check that your Resource Server enforces JWT signatures.
* **API responses** — validate your endpoints return the correct data, error formats, and pagination.
* **Performance** — measure latency and throughput to confirm baseline SLAs.
* **Compliance (optional)** — run against formal test suites if building under CDR, FDX, or similar frameworks.

***

Core Tools [#core-tools]

Postman Collection [#postman-collection]

Run an end-to-end flow using Fiskil’s official Postman collection:

* Create consents
* Retrieve tokens
* Call your Resource Server endpoints
* Inspect responses

Mock Data Recipient [#mock-data-recipient]

Fiskil maintains a CDR Mock Data Recipient you can use to simulate CDR Consent flows:

* Create consents
* Browse consumer data
* Revoke consents

***

Request Logs [#request-logs]

Every API call is recorded in [Request Logs](/data-holder/guides/telemetry/logs).

* Validate payloads, scopes, and status codes.
* Debug errors by tracing failed requests.
* Confirm traffic flows only within the granted consent.

***

Metrics [#metrics]

Each instance tracks performance and availability metrics.

* Verify throughput and latency under load.
* Check baseline error rates before go-live.

See: [Metrics](/data-holder/guides/telemetry/metrics)

***

Compliance Tools [#compliance-tools]

If your instance uses a **compliance profile** (e.g., CDR, FDX), Fiskil provides access to compliance validation tools.

* Run automated checks against required endpoints and scopes.
* Generate reports for regulators or internal audit.

<Note>
  For regulated environments, additional testing tools may be required.
  Please [contact the Fiskil team](https://fiskil.com/contact) to enable compliance testing support for your instance.
</Note>

See: [Compliance Tools](/data-holder/guides/testing/compliance-tools)

***

Environments [#environments]

Always test thoroughly in **staging** before promoting to **production**:

* Staging allows mock recipients and relaxed change controls.
* Production must remain stable and audit-ready.

***

Related [#related]

* [Using Postman](/data-holder/guides/testing/postman)
* [Request Logs](/data-holder/guides/telemetry/logs)
* [Metrics](/data-holder/guides/telemetry/metrics)
* [Compliance Tools](/data-holder/guides/testing/compliance-tools)


---

# Testing in Postman (/data-holder/guides/testing/postman)

Validate your integration end‑to‑end using our Postman collection, your mock users, and Request Logs.



This guide shows how to test your Data Provider integration **end‑to‑end** using **Postman**. You will initiate a hosted consent flow, obtain tokens, and call your Resource Server endpoints. You’ll also learn how to verify results in **Request Logs** and where to find additional tools for regulated profiles (e.g., CDR).

***

Overview [#overview]

* **Primary tool**: Postman collection provided by Fiskil
* **What you’ll test**: consent → token → Resource Server calls
* **What you provide**: mock users, accounts, and sample data in your own systems
* **Validation**: use Console → Request Logs to confirm success and investigate errors

***

Prerequisites [#prerequisites]

* A **staging** instance configured in the Console
* Your **Resource Server** live on a public HTTPS URL
* Required endpoints implemented:
  * `GET /v1/auth/customer/search`
  * `GET /v1/auth/customer/{customerId}/accounts`
  * `GET /v1/auth/customer/{customerId}`
  * At least one data endpoint (e.g., `GET /v1/customer/{customerId}/accounts/{accountId}/balances`)
* Access to the **Authorization** and **Token** endpoints, and **JWKS URL**
  *(All available in Console → **Settings → Domains**.)*

> We recommend setting up several **mock users** and **mock accounts** in your systems to test a range of scenarios (single vs joint accounts, different account types, low/no data cases, etc.).

***

Get the Postman Collection [#get-the-postman-collection]

1. Download the Fiskil **Postman collection** and **environment** (link provided in Console or by your Fiskil contact).
2. Import both into Postman.
3. Open the environment and populate variables (see next section).

***

Configure Postman Environment [#configure-postman-environment]

Set the following variables in your Postman **environment**:

* `base_url` — Your Data Provider staging environment base URL
* `jwks_url` — As shown in Console → **Settings → Domains**
* `client_id` — Provided during onboarding (or created in Console)
* `client_secret` — Provided during onboarding (or created in Console)
* `scopes` — Space-delimited list (e.g., `accounts.read balances.read`)

> All domain and endpoint values are available in the Console under **Settings → Domains** or **Settings → Resource Server**.

***

Authorize and Obtain a Token (Postman) [#authorize-and-obtain-a-token-postman]

Use Postman’s built‑in OAuth 2.0 flow:

1. In the collection, open **Authorization** on a request that uses OAuth 2.0.
2. Set:
   * **Auth URL**: `{{base_url}}/connect/authorize`
   * **Access Token URL**: `{{base_url}}/connect/token`
   * **Client ID**: `{{client_id}}`
   * **Client Secret**: `{{client_secret}}` (if applicable)
   * **Scopes**: `{{scopes}}`
   * **Grant Type**: Authorization Code (PKCE if required)
3. Click **Get New Access Token**.
4. Complete the **hosted consent screen** (Fiskil) as the test user.
5. Postman will exchange the code and store the **access token**.
6. Click **Use Token** to attach it to subsequent requests.

***

Call Your Resource Server Endpoints [#call-your-resource-server-endpoints]

With the token set in Postman, you can fetch some data:

* `GET {{base_url}}/api/v1/accounts/{{account_id}}/balances`
* Expect balance data scoped by the consent.

> Ensure your Resource Server validates the JWT (signature, `exp`, `iss/sub`, `aud`, `jti`).

***

Use Request Logs for Validation [#use-request-logs-for-validation]

Open **Console → Request Logs** to verify:

* **Successful calls** (200s) to your endpoints after consent
* **Scopes** attached to the token and used in each request
* **Error responses** (401/403) when scopes are missing or tokens are invalid/expired
* **Payload inspection** for troubleshooting

***

Creating Mock Users and Data [#creating-mock-users-and-data]

You own the user and account data surfaced by your Resource Server. For robust testing:

* Create **multiple test users** that reflect realistic personas:
  * Single user with one account
  * User with multiple accounts of different types
  * Joint/organization accounts (if supported)
* Seed **edge cases**:
  * Empty datasets (no transactions yet)
  * Restricted scopes (e.g., balances only)
  * Large pagination cases
* Keep a mapping of test users → accounts → expected results to speed up test review.

***

Common Errors [#common-errors]

* **401 Unauthorized** — Missing or invalid token. Validate signature and token lifetime.
* **400/422** — Request validation errors (missing params, malformed IDs).
* **429** — Rate limits (if configured).
* **5xx** — Upstream or Resource Server errors.

***

Running the Collection as a Suite [#running-the-collection-as-a-suite]

* Use a **Collection Runner** with a data file (CSV/JSON) of test users/accounts.
* Add **pre‑request scripts** to inject account IDs from prior responses.
* Add **tests** in Postman (e.g., `pm.expect(response.code).to.eql(200)`) to assert status codes and shapes.

***

Additional Tools for Regulated Profiles [#additional-tools-for-regulated-profiles]

If you are implementing a **Compliance Profile** (e.g., **CDR**), additional test tools and checklists are available.

* See: [Compliance & Certification Tools](/data-holder/guides/testing/compliance-tools)

> These tools complement the Postman collection with profile‑specific validation, payload rules, and certification workflows.

***

Next Steps [#next-steps]

* Review **Authentication** to confirm JWT validation and JWKS usage.
* Confirm **Consent** lifecycle and hosted screens.
* Build out additional **Resource Server** endpoints and scopes.
* Monitor **Request Logs** during ongoing development and before go‑live.


---

# Regulatory Reporting (/data-holder/guides/testing/regulatory-reporting)

How to prepare six-monthly CDR data holder reporting using Fiskil Console Analytics.



CDR Data Holders are required to submit a compliance report to the ACCC every six months via the **CDR Portal** at [portal.cdr.gov.au](https://portal.cdr.gov.au/). This guide explains how to use the Fiskil Console to find the numbers you need, and provides context on what each question in the reporting form is asking.

<Note>
  This guide is general information only and is not legal advice. Always confirm your reporting position against the latest CDR Rules and ACCC guidance.
</Note>

***

Reporting periods and due dates [#reporting-periods-and-due-dates]

The reporting periods are:

* **1 January to 30 June**
* **1 July to 31 December**

Reports must be submitted **within 30 days after the end** of each reporting period. In practice, this is typically:

* Period ending **30 June** → due **30 July**
* Period ending **31 December** → due **30 January**

***

Using the Analytics Tab [#using-the-analytics-tab]

Most of the data you need for regulatory reporting is available directly in the Fiskil Console under the **Analytics** tab. Follow these steps each reporting period.

Step 1 — Open Analytics [#step-1--open-analytics]

1. Open the [Fiskil Console](https://console.fiskil.com) and select your **Data Provider workspace** from the top-left selector.
2. Click **Analytics** in the top navigation bar.
3. You will see tiles for:
   * **Consumer Data Requests**
   * **Product Data Requests**
   * **Refusals** (Total, 403, 404, 422)

Step 2 — Select the correct environment [#step-2--select-the-correct-environment]

Use the **environment selector** in the top right to choose **Production**.

Staging is used for testing and should not be used for regulatory submissions.

Step 3 — Set your reporting period [#step-3--set-your-reporting-period]

In the **Period** section on the left, set the date range that matches your reporting period:

| Reporting Period     | Date Range to Enter     |
| -------------------- | ----------------------- |
| 1 January – 30 June  | 01/01/YYYY → 01/07/YYYY |
| 1 July – 31 December | 01/07/YYYY → 01/01/YYYY |

> **Note:** The date range picker **excludes the end date**. To capture data up to and including 31 December, enter 1 January of the following year as the end date. The same logic applies for the June period.

The tiles will update automatically once you set the date range.

***

What to Report — Question by Question [#what-to-report--question-by-question]

The tables below map each question in the reporting form to where you can find the answer in the Fiskil Console, and explain what the question is asking.

Complaints (Questions 1–7) [#complaints-questions-17]

Complaint data is managed through your own internal complaints handling system. Fiskil does not capture complaint intake or resolution — you will need to compile these figures independently.

| Question                                            | What it's asking                                                                                                                                   | Where to find it                                                                                         |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Q1 — Product data complaints                        | Total CDR complaints received relating to product data (for example, errors or gaps in your product data feed).                                    | Your internal complaints system. *Energy data holders: enter 0 — product data obligations do not apply.* |
| Q2 — Consumer complaints                            | Total CDR complaints relating to consumers or consumer data (data sharing issues, consent problems, data quality).                                 | Your internal complaints system.                                                                         |
| Q3 — Complaints by type                             | A breakdown by category used in your internal complaints process (for example, "Data accuracy", "Consent", "Access issues"). Add one row per type. | Your internal complaints system.                                                                         |
| Q4 — Complaints resolved                            | Total CDR consumer complaints resolved during the reporting period.                                                                                | Your internal complaints system.                                                                         |
| Q4.1 *(optional)* — Resolved, received this period  | Of Q4, how many were received and resolved within this same period.                                                                                | Your internal complaints system.                                                                         |
| Q4.2 *(optional)* — Resolved, received prior period | Of Q4, how many were received in a previous period but resolved this period.                                                                       | Your internal complaints system.                                                                         |
| Q5 — Average days to resolve (IDR)                  | Average calendar days from complaint received to resolved via internal dispute resolution.                                                         | Your internal complaints system.                                                                         |
| Q6 — Referred to EDR                                | Complaints referred to an external dispute resolution scheme (for example, AFCA for banking or the relevant energy ombudsman).                     | Your internal complaints system.                                                                         |
| Q7 — Resolved by EDR                                | Complaints resolved by the external dispute resolution scheme.                                                                                     | Your internal complaints system.                                                                         |

***

Data Requests (Questions 8–10) [#data-requests-questions-810]

Most data request figures come directly from the **Analytics** tab in the Fiskil Console.

For Q9 specifically, Fiskil primarily handles requests made by **accredited data recipients or intermediaries** (for example, apps or services your customers authorise). Fiskil does not generally handle direct consumer-to-data-holder request channels, so this metric is usually sourced from your own systems and often 0 unless your sector supports this flow and it has occurred.

| Question                                                | What it's asking                                                                                                                                                                                                                                                                                            | Where to find it                                                                                                     |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Q8 — Product data requests                              | Total requests received by your product data APIs during the period.                                                                                                                                                                                                                                        | **Product Data Requests** tile in Analytics. *Energy data holders: enter 0 — product data obligations do not apply.* |
| Q9 — Consumer data requests from eligible CDR consumers | Requests made directly by consumers to your APIs (rule 1.13(1)(a)(i)). Fiskil does not generally participate in this direct-consumer flow, so this metric should come from your own direct request channels. This obligation has not yet commenced for most data holders — if that applies to you, enter 0. | Your internal systems for direct consumer requests (not Fiskil Analytics).                                           |
| Q10 — Consumer data requests from accredited persons    | Requests made by accredited data recipients or intermediaries on behalf of consumers. This is the standard flow Fiskil facilitates and is usually your primary non-zero figure.                                                                                                                             | **Consumer Data Requests** tile in Analytics.                                                                        |

***

Product Data Refusals (Question 11) [#product-data-refusals-question-11]

*Energy data holders: this entire section does not apply. Enter 0 / No for all fields.*

| Question                                        | What it's asking                                                                                                                                                                                              | Where to find it in Fiskil                                                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Q11 — Did you refuse any product data requests? | Yes/No.                                                                                                                                                                                                       | Review the refusal tiles in Analytics for the reporting period.                                                                      |
| Q11.1 — Total product data refusals             | Count of all product data request refusals.                                                                                                                                                                   | **Total Refusals** tile in Analytics.                                                                                                |
| Q11.2 — 403 errors                              | Refusals due to a detected threat to the data holder, CDR Register, or consumer.                                                                                                                              | **Refusals (Error code 403)** tile in Analytics.                                                                                     |
| Q11.3 — 429 errors                              | Refusals due to traffic thresholds exceeded or denial-of-service detection.                                                                                                                                   | Contact [Fiskil Support](mailto:support@fiskil.com.au) if you need a 429 breakdown — this is not currently shown as a separate tile. |
| Q11.4 — Other refusals                          | Any other CDR Rule or Data Standard relied upon to refuse a request, with the rule cited. Under Fiskil's current implementation, this is not supported as a separate refusal pathway and is expected to be 0. | Enter **0** from Fiskil-supported flows. If you have non-Fiskil channels, verify through your own internal systems.                  |

***

Consumer Data Refusals — Direct from Consumers (Question 12) [#consumer-data-refusals--direct-from-consumers-question-12]

Fiskil primarily handles requests made by **accredited data recipients or intermediaries** (for example, apps or services your customers have authorised). Fiskil does **not** generally handle direct API requests from individual consumers or business consumers to you as a data holder.

That means Question 12 metrics are usually sourced from **your own direct consumer request channels/processes**, not from Fiskil Analytics.

For most data holders this will be uncommon and often **0**, but if your sector supports direct consumer requests and you have received them, you should report them.

| Question                                                                 | What it's asking                                                                                                                                                                          | Where to find it                                                                                                                                |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Q12 — Did you refuse consumer data requests from eligible CDR consumers? | Yes/No. If your sector has not commenced direct consumer API access, answer No.                                                                                                           | This should usually be **No / 0** unless you received and refused direct consumer requests. Not provided by Fiskil Analytics.                   |
| Q12.1 — Total refusals                                                   | Count of all refusals to direct consumer requests.                                                                                                                                        | This should usually be **0** unless you received and refused direct consumer requests. Not provided by Fiskil Analytics.                        |
| Q12.2 — 403 errors                                                       | Refusals due to a detected threat.                                                                                                                                                        | This should usually be **0** unless you received and refused direct consumer requests with this refusal type. Not provided by Fiskil Analytics. |
| Q12.3 — 404 errors                                                       | Refusals returned for a blocked or suspended account.                                                                                                                                     | This should usually be **0** unless you received and refused direct consumer requests with this refusal type. Not provided by Fiskil Analytics. |
| Q12.4 — 422 errors                                                       | Refusals returned for a blocked or suspended account (alternative code used in some standards contexts).                                                                                  | This should usually be **0** unless you received and refused direct consumer requests with this refusal type. Not provided by Fiskil Analytics. |
| Q12.5 — 429 errors                                                       | Refusals due to traffic thresholds or denial-of-service detection.                                                                                                                        | This should usually be **0** unless you received and refused direct consumer requests with this refusal type. Not provided by Fiskil Analytics. |
| Q12.6 — Other refusals                                                   | Any other CDR Rule or Data Standard relied upon, with the rule cited. Under Fiskil's current implementation, this is not supported as a separate refusal pathway and is expected to be 0. | This should usually be **0**. Not provided by Fiskil Analytics.                                                                                 |

***

Consumer Data Refusals — From Accredited Persons (Question 13) [#consumer-data-refusals--from-accredited-persons-question-13]

This section mirrors Question 12 but covers requests made by **accredited data recipients or intermediaries** on behalf of consumers — the standard flow Fiskil facilitates. This is where most data holders will have non-zero figures.

| Question                                                             | What it's asking                                                                                                                                                                          | Where to find it in Fiskil                                                                                          |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Q13 — Did you refuse consumer data requests from accredited persons? | Yes/No.                                                                                                                                                                                   | Review refusal tiles in Analytics.                                                                                  |
| Q13.1 — Total refusals                                               | Count of all refusals to accredited-person requests.                                                                                                                                      | **Total Refusals to share consumer data** tile in Analytics.                                                        |
| Q13.2 — 403 errors                                                   | Refusals due to a detected threat.                                                                                                                                                        | **Refusals (Error code 403)** tile in Analytics.                                                                    |
| Q13.3 — 404 errors                                                   | Refusals returned for a blocked or suspended account.                                                                                                                                     | **Refusals (Error code 404)** tile in Analytics.                                                                    |
| Q13.4 — 422 errors                                                   | Refusals returned for a blocked or suspended account.                                                                                                                                     | **Refusals (Error code 422)** tile in Analytics.                                                                    |
| Q13.5 — 429 errors                                                   | Refusals due to traffic thresholds or denial-of-service detection.                                                                                                                        | Contact [Fiskil Support](mailto:support@fiskil.com.au) if you need a 429 breakdown.                                 |
| Q13.6 — Other refusals                                               | Any other CDR Rule or Data Standard relied upon, with the rule cited. Under Fiskil's current implementation, this is not supported as a separate refusal pathway and is expected to be 0. | Enter **0** from Fiskil-supported flows. If you have non-Fiskil channels, verify through your own internal systems. |

***

Sector Applicability Summary [#sector-applicability-summary]

| Question Group                  | Banking & Non-Bank Lenders | Energy Data Holders           |
| ------------------------------- | -------------------------- | ----------------------------- |
| Q1 — Product data complaints    | Required                   | Not applicable — enter 0      |
| Q2–7 — Consumer complaints      | Required                   | Required                      |
| Q8 — Product data requests      | Required                   | Not applicable — enter 0      |
| Q9–10 — Consumer data requests  | Required                   | Required                      |
| Q11 — Product data refusals     | Required                   | Not applicable — enter 0 / No |
| Q12–13 — Consumer data refusals | Required                   | Required                      |

***

Common Questions [#common-questions]

**What if a value is zero?**
Enter 0. Do not leave numeric fields blank.

**What counts as a CDR complaint?**
Any complaint that relates to your CDR obligations — product data availability, consumer data sharing, consent and authorisation, or CDR-related service issues. General complaints unrelated to CDR do not need to be counted.

**What is the difference between Q12 and Q13?**
Q12 covers requests made directly by consumers to your APIs. Q13 covers requests made by accredited data recipients or intermediaries on behalf of consumers — this is the standard flow Fiskil facilitates and where most data holders will see activity.

**I need more detail than the Analytics tiles provide.**
The **Logs** tab in the Fiskil Console provides a full request-level log that you can use to verify or investigate the totals shown in Analytics. If you need data that is not available in the Console, contact [Fiskil Support](mailto:support@fiskil.com.au).

***

Further Resources [#further-resources]

* [CDR Portal](https://portal.cdr.gov.au/)
* [CDR Rules — Rule 9.4 (Reporting obligations)](https://www.legislation.gov.au/Series/F2020L00094)
* [Consumer Data Standards](https://consumerdatastandardsaustralia.github.io/standards/)
* [Metrics](/data-holder/guides/telemetry/metrics)
* [Compliance Tools](/data-holder/guides/testing/compliance-tools)
* [Go Live Checklist](/data-holder/guides/go-live)
* [Fiskil Support](mailto:support@fiskil.com.au)


---

# Logs (/data-holder/guides/telemetry/logs)

View and export Data Provider request logs via the Console or forward to your SIEM/observability tools.



Request Logs give you visibility into every call made through your Data Provider. They are essential for:

* Debugging integration issues
* Auditing consented data access
* Monitoring performance and latency
* Forwarding events into your SIEM or observability stack

***

Log Structure [#log-structure]

Fiskil exports logs with the following structure. Note that this structure may evolve in future versions.

* `request_id` — Request identifier (string)
* `consent_id` — Consent ID / CDR arrangement ID (string)
* `fapi_interaction_id` — FAPI interaction ID (string)
* `account_id` — Canonical identifier for the account, if applicable (string)
* `customer_id` — Identifier for the customer, if applicable (string)
* `app_name` — ADR client name requesting data (string)
* `level` — Severity level: "ERROR", "WARN", or "INFO" (string)
* `error_reason` — Human-readable description for error reason (string)
* `status_code` — HTTP status code of the request (number)
* `route_pattern` — Request route pattern for API endpoint accessed (string)
* `path` — Request path for API endpoint accessed (string)
* `query` — HTTP request query parameters (string)
* `method` — HTTP request method (string)
* `latency_ms` — Time taken for the request in milliseconds (number)
* `ip` — IPv4 address of the request origin (string)
* `response_body_size` — HTTP response body size in bytes (number)
* `timestamp` — ISO 8601 timestamp of the request (string)
* `trace_id` — Fiskil internal trace identifier (string)

***

Viewing Logs in the Console [#viewing-logs-in-the-console]

Access real-time request logs directly in the [Fiskil Console](https://console.fiskil.com/data-holder/logs) for immediate debugging and monitoring.

<Note>
  The request logs interface provides filtering options and log entry visualization for immediate debugging and monitoring.
</Note>

Filtering and Search [#filtering-and-search]

The Console provides powerful filtering capabilities to help you find specific requests quickly:

* **Customer ID** — Filter by specific customer identifiers
* **Consent ID** — View logs for specific consent arrangements
* **Route** — Filter by API endpoint patterns
* **Time range** — Narrow down to specific time periods
* **HTTP status** — Focus on errors, successes, or specific response codes
* **HTTP method** — Filter by GET, POST, PUT, DELETE operations

Detailed Log View [#detailed-log-view]

Click on any individual log entry to expand and view comprehensive details including:

* ADR application name and metadata
* Internal trace ID for debugging
* Associated account IDs
* Request and response timing
* Complete error context when applicable

<Tip>
  Use the expanded log view to quickly identify integration issues and trace request flows through your system.
</Tip>

***

Log Drains [#log-drains]

**Log Drains** are a powerful feature that automatically forwards your Data Provider request logs to external observability and SIEM tools. This enables you to:

* Integrate logs into your existing monitoring infrastructure
* Set up automated alerting and analysis
* Maintain centralized log storage and retention policies
* Perform advanced analytics across your entire tech stack

How Log Drains Work [#how-log-drains-work]

Configure [Log Drains](https://console.fiskil.com/data-holder/settings/log-drains) in the Console to create a real-time stream of log events from your Data Provider to your chosen destination.

Supported Destinations [#supported-destinations]

<CardGroup cols={2}>
  <Card title="Azure Monitor" icon="microsoft">
    **Application Insights** — Stream logs directly to Azure's monitoring platform with full KQL query support.
  </Card>

  <Card title="Elasticsearch" icon="magnifying-glass">
    **Data Streams** — Forward logs to your Elasticsearch cluster as structured data streams.
  </Card>
</CardGroup>

<Info>
  Need integration with a different observability tool? Contact [support](https://fiskil.atlassian.net/servicedesk/customer/portal/6/group/23/create/93) to discuss custom integrations.
</Info>

***

Setting Up Log Drains [#setting-up-log-drains]

Azure Monitor Configuration [#azure-monitor-configuration]

Logs are delivered to Azure via Application Insights. Steps:

<Steps>
  <Step>
    Create a new application in Azure Monitor Application Insights
  </Step>

  <Step>
    Copy the "Connection String"
  </Step>

  <Step>
    Go to the Log Drain settings in the Fiskil Console
  </Step>

  <Step>
    Click the Azure card
  </Step>

  <Step>
    Enter your connection string
  </Step>

  <Step>
    Save your log drain
  </Step>
</Steps>

It may take a few minutes for logs to appear in Azure.
The log attributes are in `customDimensions` of the record, and you can query them with [KQL](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/log-query-overview).

***

Elasticsearch Configuration [#elasticsearch-configuration]

Logs are delivered to Elasticsearch as a data stream. Authentication requires an API key.

<Steps>
  <Step>
    Create an API Key with privileges:

    ```json
    PUT /_security/api_key
    {
        "name": "fiskil-ingest",
        "role_descriptors": {
            "logs_fiskil_holder_ingest_role": {
                "index": [
                    {
                        "names": ["logs-fiskil-holder"],
                        "privileges": ["write"]
                    }
                ]
            }
        }
    }
    ```
  </Step>

  <Step>
    Go to Log Drain settings in the Console
  </Step>

  <Step>
    Click the Elasticsearch card
  </Step>

  <Step>
    Enter your cluster endpoint and encoded API Key
  </Step>

  <Step>
    Save your log drain
  </Step>
</Steps>

It may take a few minutes for logs to begin streaming into your Elasticsearch cluster.


---

# Metrics (/data-holder/guides/telemetry/metrics)

Comprehensive operational metrics tracked automatically for compliance, performance monitoring, and business insights.



Every Fiskil instance automatically captures a comprehensive set of operational metrics covering performance, availability, traffic patterns, and authorization activity. These metrics are essential for compliance with consumer data standards and provide valuable insights for monitoring and capacity planning.

<Note>
  Metrics are collected continuously and used for compliance reporting. Console visibility and export capabilities are coming soon.
</Note>

***

Performance & Availability Metrics [#performance--availability-metrics]

<CardGroup cols={2}>
  <Card title="Availability Monitoring" icon="chart-line">
    Track instance uptime and service availability over time periods to ensure SLA compliance.
  </Card>

  <Card title="Performance Tracking" icon="gauge-high">
    Monitor API response times and success rates against defined performance thresholds.
  </Card>
</CardGroup>

| Metric                    | Description                                                      | Use Case                                                |
| ------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------- |
| **Availability**          | Percentage of time your instance is available to serve requests  | SLA monitoring and compliance reporting                 |
| **Performance**           | Percentage of API calls completing within performance thresholds | Identify performance degradation and optimization needs |
| **Average Response Time** | Mean response time from your Resource Server in milliseconds     | Performance tuning and capacity planning                |

***

Traffic & Usage Metrics [#traffic--usage-metrics]

Understanding traffic patterns and usage helps with capacity planning and identifying trends in data sharing adoption. [Fiskil Firewall](/data-holder/guides/security/firewall) also throttles data recipients and blocks abusive traffic so your Resource Server sees a bounded load.

| Metric            | Description                                                   | Key Insights                               |
| ----------------- | ------------------------------------------------------------- | ------------------------------------------ |
| **Invocations**   | Total number of API calls received, segmented by time periods | Traffic volume and usage patterns          |
| **Average TPS**   | Average transactions per second over time                     | Steady-state load characteristics          |
| **Peak TPS**      | Maximum observed transactions per second                      | Peak capacity requirements                 |
| **Session Count** | Number of active sessions (access token provisioning events)  | User engagement and authorization activity |

***

Authorization & Compliance Metrics [#authorization--compliance-metrics]

<Tabs items={["User Activity", "Error Tracking", "Secondary Holders"]}>
  <Tab value="User Activity">
    Track customer and recipient engagement with your data sharing platform.

    | Metric                   | Description                                                 |
    | ------------------------ | ----------------------------------------------------------- |
    | **Customer Count**       | Number of customers with active authorizations              |
    | **Data Recipient Count** | Number of recipient applications with active authorizations |
    | **Authorizations**       | Total authorizations processed over time                    |
  </Tab>

  <Tab value="Error Tracking">
    Monitor error rates and rejected requests for operational health.

    | Metric         | Description                                    |
    | -------------- | ---------------------------------------------- |
    | **Errors**     | API calls resulting in error responses         |
    | **Rejections** | Calls rejected due to traffic threshold limits |
  </Tab>

  <Tab value="Secondary Holders">
    For shared-responsibility deployments with secondary data holders.

    | Metric                          | Description                                 |
    | ------------------------------- | ------------------------------------------- |
    | **Secondary Holder Errors**     | Errors received from secondary data holders |
    | **Secondary Holder Rejections** | Rejections from secondary data holders      |
  </Tab>
</Tabs>

***

How Metrics Support Your Operations [#how-metrics-support-your-operations]

<AccordionGroup>
  <Accordion title="Compliance & Regulatory Reporting">
    Metrics are automatically tracked in accordance with consumer data standards (CDR, FDX, etc.), ensuring you meet regulatory requirements without manual effort.
  </Accordion>

  <Accordion title="Performance Optimization">
    Monitor response times, throughput, and error rates to identify optimization opportunities and ensure your Resource Server meets performance targets.
  </Accordion>

  <Accordion title="Capacity Planning">
    Use traffic patterns, peak TPS, and session counts to plan infrastructure scaling and anticipate future capacity needs.
  </Accordion>

  <Accordion title="Audit Readiness">
    Maintain verifiable records of availability, authorization activity, and performance metrics for compliance audits and regulatory reviews.
  </Accordion>
</AccordionGroup>

***

Current Availability [#current-availability]

<CardGroup cols={3}>
  <Card title="Automatic Collection" icon="check-circle">
    All metrics are tracked continuously by Fiskil without any configuration required.
  </Card>

  <Card title="Compliance Ready" icon="shield-check">
    Metrics collection meets consumer data standard requirements for operational monitoring.
  </Card>

  <Card title="Coming Soon" icon="clock">
    Console visibility and external system export capabilities are in development.
  </Card>
</CardGroup>

<Info>
  We'll announce when metrics become available for viewing in the Console or export to external monitoring systems.
</Info>

***

Related Documentation [#related-documentation]

<Cards>
  <Card title="Request Logs" href="/data-holder/guides/telemetry/logs" icon={<DatabaseRestore />}>
    View detailed request-level logs and configure log drains to external systems.
  </Card>

  <Card title="Go Live Checklist" href="/data-holder/guides/go-live" icon={<Building />}>
    Ensure your instance is ready for production with our comprehensive checklist.
  </Card>

  <Card title="Security & Compliance" href="/data-holder/guides/security/sso" icon={<Phone />}>
    Learn about Fiskil's security measures and compliance certifications.
  </Card>
</Cards>


---

# API Testing (/data-holder/guides/product-portal/api-testing)

Test your CDR Products endpoint directly from the Console to verify how products are exposed in staging and production.



API Testing [#api-testing]

<Info>
  API Testing is currently in **Beta**. This feature allows you to verify your product data through the CDR Products endpoint without leaving the [Console](https://console.fiskil.com/).
</Info>

The API Test feature provides a built-in way to verify how your products are exposed through the CDR API in both Staging and Production environments. Use it to confirm your product configuration is correct before and after publishing changes.

<Card title="Open Product Portal" icon="arrow-up-right-from-square" href="https://console.fiskil.com/data-holder/products">
  Access the API Test feature in the Fiskil Console.
</Card>

***

Why use API Testing [#why-use-api-testing]

<CardGroup cols={2}>
  <Card title="Instant verification" icon="bolt">
    Test your Products endpoint directly from [Product Portal](https://console.fiskil.com/data-holder/products) without switching tools.
  </Card>

  <Card title="Environment comparison" icon="code-compare">
    Compare API responses between Staging and Production to verify deployments.
  </Card>

  <Card title="Debug configuration" icon="bug">
    Quickly identify issues with product data or API exposure settings.
  </Card>

  <Card title="Validate before go-live" icon="shield-check">
    Confirm your products appear correctly in the API before publishing to Production.
  </Card>
</CardGroup>

***

Accessing API Test [#accessing-api-test]

<Steps>
  <Step title="Navigate to Product Portal">
    In the [Fiskil Console](https://console.fiskil.com/), go to **[Product Portal](https://console.fiskil.com/data-holder/products)** from the main navigation.
  </Step>

  <Step title="Open API Test">
    Click the **Test API** button in the top-right corner of the Products page.
  </Step>

  <Step title="View the API Test panel">
    The API Test panel opens, showing the CDR Products endpoint configuration and response preview.
  </Step>
</Steps>

***

Using the API Test panel [#using-the-api-test-panel]

The API Test panel provides a complete interface for testing your Products endpoint.

Select environment [#select-environment]

Choose which environment to test against:

| Environment    | Use case                                                       |
| -------------- | -------------------------------------------------------------- |
| **Staging**    | Verify new products or changes before publishing to Production |
| **Production** | Confirm live product data is correct and accessible            |

<Tip>
  Always test in Staging first when making changes. Once verified, publish to Production and test again to confirm the deployment.
</Tip>

Request configuration [#request-configuration]

The panel displays the following request details:

<ResponseField name="Request URL" type="string">
  The full URL of the CDR Products endpoint for your Data Provider. This is automatically populated based on your instance configuration and selected environment.
</ResponseField>

<ResponseField name="Headers" type="object">
  Required headers for the API request, including the `x-v` header specifying the API version.

  <Expandable title="Common headers">
    <ResponseField name="x-v" type="integer">
      The version of the API being called. Currently supports version `4`.
    </ResponseField>
  </Expandable>
</ResponseField>

Send a request [#send-a-request]

Click **Send Request** to execute the API call. The response appears in the panel below.

***

Understanding the response [#understanding-the-response]

After sending a request, the API Test panel displays:

Response status [#response-status]

A status badge indicates the result:

| Status               | Description                            |
| -------------------- | -------------------------------------- |
| **200 OK**           | Request successful — products returned |
| **400 Bad Request**  | Invalid request parameters             |
| **401 Unauthorized** | Authentication failed                  |
| **404 Not Found**    | Endpoint not found                     |
| **500 Server Error** | Internal server error                  |

Response body [#response-body]

The response body shows the JSON payload returned by the Products endpoint. The Get Products endpoint returns a list of products with core fields:

```json Get Products response
{
  "data": {
    "products": [
      {
        "productId": "home-loan-variable-001",
        "name": "Standard Variable Home Loan",
        "description": "Our standard variable rate home loan for owner occupiers with flexible repayment options.",
        "brand": "Example Bank",
        "brandName": "Example Bank",
        "productCategory": "RESIDENTIAL_MORTGAGES",
        "isTailored": false,
        "lastUpdated": "2025-01-15T09:30:00Z",
        "additionalInformation": {
          "overviewUri": "https://www.example.com.au/home-loans/variable",
          "termsUri": "https://www.example.com.au/home-loans/terms",
          "eligibilityUri": "https://www.example.com.au/home-loans/eligibility",
          "feesAndPricingUri": "https://www.example.com.au/home-loans/fees"
        }
      }
    ]
  },
  "links": {
    "self": "https://api.example.com.au/cds-au/v1/banking/products"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1
  }
}
```

To retrieve the full product details including rates, fees, and features, call the Get Product Detail endpoint:

```json Get Product Detail response
{
  "data": {
    "productId": "home-loan-variable-001",
    "name": "Standard Variable Home Loan",
    "description": "Our standard variable rate home loan for owner occupiers with flexible repayment options.",
    "brand": "Example Bank",
    "brandName": "Example Bank",
    "productCategory": "RESIDENTIAL_MORTGAGES",
    "isTailored": false,
    "lastUpdated": "2025-01-15T09:30:00Z",
    "additionalInformation": {
      "overviewUri": "https://www.example.com.au/home-loans/variable",
      "termsUri": "https://www.example.com.au/home-loans/terms",
      "eligibilityUri": "https://www.example.com.au/home-loans/eligibility",
      "feesAndPricingUri": "https://www.example.com.au/home-loans/fees"
    },
    "features": [
      {
        "featureType": "OFFSET",
        "additionalInfo": "100% offset account available"
      },
      {
        "featureType": "REDRAW",
        "additionalInfo": "Free redraw facility available"
      },
      {
        "featureType": "DIGITAL_BANKING",
        "additionalInfo": "Manage your loan via online and mobile banking"
      }
    ],
    "eligibility": [
      {
        "eligibilityType": "MIN_AGE",
        "additionalValue": "18"
      },
      {
        "eligibilityType": "RESIDENCY_STATUS",
        "additionalValue": "Australian citizen or permanent resident"
      }
    ],
    "fees": [
      {
        "name": "Application Fee",
        "feeType": "UPFRONT",
        "amount": "600.00",
        "currency": "AUD"
      },
      {
        "name": "Monthly Service Fee",
        "feeType": "PERIODIC",
        "amount": "10.00",
        "currency": "AUD",
        "additionalValue": "P1M"
      }
    ],
    "lendingRates": [
      {
        "lendingRateType": "VARIABLE",
        "rate": "0.0649",
        "comparisonRate": "0.0672",
        "calculationFrequency": "P1D",
        "applicationFrequency": "P1M",
        "interestPaymentDue": "IN_ARREARS",
        "repaymentType": "PRINCIPAL_AND_INTEREST",
        "loanPurpose": "OWNER_OCCUPIED",
        "additionalInfo": "Standard variable rate for owner occupied, principal and interest repayments"
      }
    ],
    "constraints": [
      {
        "constraintType": "MIN_LIMIT",
        "additionalValue": "50000.00"
      },
      {
        "constraintType": "MAX_LIMIT",
        "additionalValue": "5000000.00"
      }
    ]
  },
  "links": {
    "self": "https://api.example.com.au/cds-au/v1/banking/products/home-loan-variable-001"
  }
}
```

<Note>
  The response follows the [CDR Banking Product API specification](https://consumerdatastandardsaustralia.github.io/standards/#get-products). Rates are expressed as decimals (e.g., `0.0649` represents 6.49%). Refer to the standard for complete field definitions.
</Note>

***

Common testing scenarios [#common-testing-scenarios]

Verify a new product [#verify-a-new-product]

After creating a product in Product Portal:

<Steps>
  <Step title="Deploy to Staging">
    Deploy your new product to the Staging environment.
  </Step>

  <Step title="Open API Test">
    Click **Test API** and select **Staging** as the environment.
  </Step>

  <Step title="Send request">
    Click **Send Request** and verify your product appears in the response.
  </Step>

  <Step title="Check product fields">
    Confirm all fields are correctly populated, including:

    * `productId`
    * `name`
    * `description`
    * `productCategory`
    * `lastUpdated`
  </Step>
</Steps>

Compare Staging and Production [#compare-staging-and-production]

To verify a deployment was successful:

<Steps>
  <Step title="Test Staging">
    Select **Staging** environment and send a request. Note the products and their `lastUpdated` timestamps.
  </Step>

  <Step title="Test Production">
    Switch to **Production** environment and send a request.
  </Step>

  <Step title="Compare responses">
    Verify the expected products appear in Production with the correct data.
  </Step>
</Steps>

Debug missing products [#debug-missing-products]

If a product doesn't appear in the API response:

<AccordionGroup>
  <Accordion title="Product not deployed">
    Check the product status in [Product Portal](https://console.fiskil.com/data-holder/products). Products must be deployed to appear in the API.

    * **NEEDS\_REVIEW** — Product has pending changes that need approval
    * **DRAFT** — Product not yet deployed
    * **PUBLISHED** — Product is live
  </Accordion>

  <Accordion title="Wrong environment selected">
    Verify you're testing the correct environment. Products deployed to Staging won't appear in Production until published.
  </Accordion>

  <Accordion title="Product archived">
    Archived products may not appear in the Products list endpoint. Check if the product has an expired `effectiveTo` date.
  </Accordion>

  <Accordion title="Validation errors">
    Products with validation errors cannot be deployed. Return to the product editor and resolve any errors shown.
  </Accordion>
</AccordionGroup>

***

Best practices [#best-practices]

<CardGroup cols={2}>
  <Card title="Test after every deployment" icon="rotate">
    Always verify the API response after deploying changes to catch issues early.
  </Card>

  <Card title="Compare environments regularly" icon="code-compare">
    Regularly compare Staging and Production to ensure they're in sync as expected.
  </Card>

  <Card title="Check timestamps" icon="clock">
    Use the `lastUpdated` field to confirm you're seeing the latest version of your products.
  </Card>

  <Card title="Document issues" icon="file-lines">
    If you encounter unexpected responses, note the details before contacting support.
  </Card>
</CardGroup>

***

Limitations [#limitations]

<Warning>
  API Testing is currently in Beta and has the following limitations:
</Warning>

* **Products endpoint only** — Currently supports testing the Get Products endpoint. Additional endpoints may be added in future releases.
* **Read-only** — You cannot modify product data through the API Test panel.
* **No authentication testing** — The test uses internal authentication. It does not test external client authentication flows.

***

Related resources [#related-resources]

<CardGroup cols={2}>
  <Card title="Creating products" icon="plus" href="/data-holder/guides/product-portal/creating-products">
    Learn how to create and manage products in Product Portal.
  </Card>

  <Card title="Platform API Reference" icon="list" href="/data-holder/platform-api/introduction">
    Manage products programmatically via the Platform API.
  </Card>

  <Card title="Testing with Postman" icon="rocket" href="/data-holder/guides/testing/postman">
    Use Postman for more advanced API testing scenarios.
  </Card>

  <Card title="CDR integration requirements" icon="book" href="/data-holder/api-reference/cdr/integration-requirements">
    Understand the technical requirements for CDR API integration.
  </Card>
</CardGroup>


---

# Creating and managing products (/data-holder/guides/product-portal/creating-products)

Learn how to create, edit, approve, and publish products in Product Portal.



This guide walks you through the complete lifecycle of managing products in Product Portal — from creating your first product to publishing changes to production.

Before you start [#before-you-start]

<Check>
  Make sure you have access to the [Fiskil Console](https://console.fiskil.com/) with appropriate permissions for [Product Portal](https://console.fiskil.com/data-holder/products).
</Check>

<Info>
  All product changes follow a controlled workflow: create or edit in **Staging**, review and approve, then publish to **Production**.
</Info>

***

Product lifecycle overview [#product-lifecycle-overview]

Every product in Product Portal follows a consistent lifecycle:

<Steps>
  <Step title="Create or edit">
    Add a new product or make changes to an existing one. All changes start in draft mode.
  </Step>

  <Step title="Review and validate">
    Review your changes in the [Console](https://console.fiskil.com/). Validation errors are shown inline before you can proceed.
  </Step>

  <Step title="Deploy to Staging">
    Deploy your product to the Staging environment for testing. You can verify the product data through the API.
  </Step>

  <Step title="Approve and publish">
    Once validated, approve the changes and publish to Production. This makes the product available to data recipients.
  </Step>
</Steps>

***

Creating a new product [#creating-a-new-product]

<Steps>
  <Step title="Navigate to Product Portal">
    In the [Fiskil Console](https://console.fiskil.com/), go to **[Product Portal](https://console.fiskil.com/data-holder/products)** from the main navigation.
  </Step>

  <Step title="Click Add New Product">
    Select **+ Add New Product** to open the product form.
  </Step>

  <Step title="Complete required fields">
    Fill in the mandatory product details:

    | Field                | Description                                     |
    | -------------------- | ----------------------------------------------- |
    | **Product ID**       | Unique identifier (e.g., `savings-account-001`) |
    | **Product name**     | Display name shown to customers                 |
    | **Product category** | Category from the regulated specification       |
    | **Description**      | Short public description of the product         |

    <Note>
      See the [Platform API Reference](/data-holder/platform-api/introduction) for a complete list of all available fields.
    </Note>
  </Step>

  <Step title="Add optional details">
    Expand additional sections to configure:

    * **Features** — capabilities like digital banking, offset accounts
    * **Eligibility** — who can apply for the product
    * **Fees** — charges and optional discounts
    * **Rates** — deposit or lending rates with tiers
    * **Bundles** — group products together
  </Step>

  <Step title="Save draft">
    Click **Save** to store your product as a draft. You can continue editing before deploying.
  </Step>
</Steps>

***

Editing an existing product [#editing-an-existing-product]

<Steps>
  <Step title="Find the product">
    Use the search or filter options in [Product Portal](https://console.fiskil.com/data-holder/products) to locate the product you want to edit.
  </Step>

  <Step title="Open the product">
    Click on the product row to open the product detail view.
  </Step>

  <Step title="Click Edit">
    Select **Edit** to enable editing mode. This creates a new draft version of the product.

    <Warning>
      Changes are not visible to data recipients until you deploy and publish them.
    </Warning>
  </Step>

  <Step title="Make your changes">
    Update any fields as needed. The form validates your changes in real time.
  </Step>

  <Step title="Save and review">
    Save your changes and review the diff to confirm what has changed.
  </Step>
</Steps>

***

Deploying to Staging [#deploying-to-staging]

Before publishing to production, you should validate your changes in Staging.

<Steps>
  <Step title="Review your draft">
    Open the product and review the pending changes. The [Console](https://console.fiskil.com/) shows a diff of what will be deployed.
  </Step>

  <Step title="Deploy to Staging">
    Click **Deploy to Staging**. This pushes your product data to the Staging environment.
  </Step>

  <Step title="Verify via API">
    Use the built-in **Test API** feature to verify your product appears correctly:

    1. Click **Test API** in the top-right corner of [Product Portal](https://console.fiskil.com/data-holder/products)
    2. Select **Staging** as the environment
    3. Click **Send Request** to view your products

    <Tip>
      The [API Testing](/data-holder/guides/product-portal/api-testing) feature lets you verify products without leaving the [Console](https://console.fiskil.com/). For more advanced testing, use [Postman](/data-holder/guides/testing/postman).
    </Tip>
  </Step>

  <Step title="Fix any issues">
    If you find issues, return to the [Console](https://console.fiskil.com/), edit the product, and redeploy to Staging.
  </Step>
</Steps>

***

Approving and publishing to Production [#approving-and-publishing-to-production]

Once your product is validated in Staging, you can publish it to Production.

<Steps>
  <Step title="Request approval">
    If your organisation uses approval workflows, submit the product for review.
  </Step>

  <Step title="Approve changes">
    An authorised approver reviews and approves the changes.

    <Note>
      Approval workflows are configurable. Contact the Fiskil team to set up approval rules for your organisation.
    </Note>
  </Step>

  <Step title="Publish to Production">
    Click **Publish to Production**. The product is now live and accessible to data recipients.

    <Check>
      Your product is now visible in the public Products API endpoint.
    </Check>
  </Step>
</Steps>

***

Scheduling product updates [#scheduling-product-updates]

Product Portal supports scheduling changes to go live at a future date and time.

<Steps>
  <Step title="Prepare your changes">
    Edit the product and save your changes as a draft.
  </Step>

  <Step title="Set effective date">
    When deploying, select **Schedule** and choose the date and time for the changes to take effect.
  </Step>

  <Step title="Confirm schedule">
    The [Console](https://console.fiskil.com/) shows the scheduled deployment. You can cancel or modify the schedule before it executes.
  </Step>
</Steps>

<Info>
  Scheduled changes are applied automatically at the specified time. No manual action is required once scheduled.
</Info>

***

Archiving products [#archiving-products]

When a product is discontinued or no longer offered:

<Steps>
  <Step title="Open the product">
    Navigate to the product you want to archive.
  </Step>

  <Step title="Set effective dates">
    Update the **Effective To** date to indicate when the product is no longer available for new applications.
  </Step>

  <Step title="Archive the product">
    Select **Archive** to remove the product from active listings. Archived products remain in the system for historical reference.

    <Warning>
      Archived products may still appear in API responses if they are linked to existing customer accounts.
    </Warning>
  </Step>
</Steps>

***

Best practices [#best-practices]

<CardGroup cols={2}>
  <Card title="Test in Staging first" icon="flask">
    Always deploy and verify products in Staging before publishing to Production.
  </Card>

  <Card title="Use descriptive IDs" icon="tag">
    Choose product IDs that are meaningful and consistent across your organisation.
  </Card>

  <Card title="Document changes" icon="file-lines">
    Add notes when editing products to maintain a clear audit trail.
  </Card>

  <Card title="Review before publishing" icon="magnifying-glass">
    Use the diff view to confirm changes before publishing to Production.
  </Card>
</CardGroup>

***

Validation rules [#validation-rules]

Product Portal validates your data against the regulated specification. Common validation errors include:

| Error                          | Cause                        | Solution                          |
| ------------------------------ | ---------------------------- | --------------------------------- |
| **Missing required field**     | A mandatory field is empty   | Complete all required fields      |
| **Invalid enum value**         | Value not in allowed list    | Select from the dropdown options  |
| **Duplicate product ID**       | Product ID already exists    | Choose a unique product ID        |
| **Invalid URI format**         | URL is malformed             | Ensure URLs start with `https://` |
| **Conditional field required** | A dependent field is missing | See the field's conditional rules |

<Tip>
  Refer to the [Platform API Reference](/data-holder/platform-api/introduction) for detailed validation rules for each field.
</Tip>

***

Related resources [#related-resources]

<CardGroup cols={2}>
  <Card title="Platform API Reference" icon="list" href="/data-holder/platform-api/introduction">
    Manage products programmatically via the Platform API.
  </Card>

  <Card title="API Testing" icon="flask" href="/data-holder/guides/product-portal/api-testing">
    Test your CDR Products endpoint directly from the Console.
  </Card>

  <Card title="Testing with Postman" icon="rocket" href="/data-holder/guides/testing/postman">
    Verify your product data using Postman collections.
  </Card>
</CardGroup>


---

# What is Product Portal (/data-holder/guides/product-portal/what-is-product-portal)

Learn how Product Portal helps you manage, approve, and publish compliant product data.



Product Portal [#product-portal]

[Product Portal](https://console.fiskil.com/data-holder/products) is Fiskil's product management system for creating and publishing product. It supports publishing via regulated APIs (such as the Consumer Data Right). It provides a central place for your team to maintain product information, safely make changes, and ensure updates are reviewed and deployed correctly.

<Card title="Open Product Portal" icon="arrow-up-right-from-square" href="https://console.fiskil.com/data-holder/products">
  Access Product Portal in the Fiskil Console to manage your products.
</Card>

***

What you can do with Product Portal [#what-you-can-do-with-product-portal]

<CardGroup cols={2}>
  <Card title="Create and maintain products" icon="plus">
    Build your product catalogue in a single, structured repository with full field validation.
  </Card>

  <Card title="Edit products safely" icon="pen-to-square">
    Make changes using a built-in workflow with drafts, approvals, and audit logging.
  </Card>

  <Card title="Schedule updates" icon="calendar">
    Set product changes to go live at a future date and time automatically.
  </Card>

  <Card title="Test before publishing" icon="flask" href="/data-holder/guides/product-portal/api-testing">
    Deploy changes to Staging and verify through the API before publishing to Production.
  </Card>
</CardGroup>

***

When to use Product Portal [#when-to-use-product-portal]

Product Portal is designed for organisations that need to:

* Maintain product information in a controlled, digital and scalable way
* Share product data through regulated standards (for example, CDR product reference data)
* Ensure changes are reviewed and approved before publishing
* Support compliance workflows, change approvals, and auditing

***

Product environments [#product-environments]

Product Portal supports a standard environment workflow to ensure changes are validated before going live.

<Steps>
  <Step title="Staging (testing)">
    Used to validate new products and changes before publishing. Deploy here first to test the API output.
  </Step>

  <Step title="Production (live)">
    Where approved products and changes are published for data recipients. Only deploy after Staging validation.
  </Step>
</Steps>

<Tip>
  If you need additional environments (for example, staging or sandbox), [contact the Fiskil team](https://www.fiskil.com/contact).
</Tip>

***

Next steps [#next-steps]

<CardGroup cols={2}>
  <Card title="Create your first product" icon="rocket" href="/data-holder/guides/product-portal/creating-products">
    Learn how to create, edit, and publish products step by step.
  </Card>

  <Card title="Platform API Reference" icon="list" href="/data-holder/platform-api/introduction">
    Manage products programmatically via the Platform API.
  </Card>

  <Card title="Test your API" icon="flask" href="/data-holder/guides/product-portal/api-testing">
    Verify how your products are exposed through the CDR API.
  </Card>
</CardGroup>


---

# Financial-grade API (FAPI) (/data-holder/guides/security/fapi)

How Fiskil implements the FAPI 2.0 Security Profile and Message Signing profile to protect financial data sharing with mTLS, PAR, DPoP, and PKCE.



Fiskil implements the [FAPI 2.0 Security Profile](https://openid.net/wg/fapi/) for confidential clients, including PAR, PKCE with S256, issuer identification, sender-constrained access tokens using mTLS or DPoP, and client authentication using mTLS or `private_key_jwt`. Where required by an ecosystem, Fiskil also supports the separate FAPI 2.0 Message Signing profile, including JAR and JARM.

***

Why FAPI Matters [#why-fapi-matters]

The **Financial-grade API (FAPI)** security profile, developed by the OpenID Foundation, defines the highest standard for securing API-based data sharing. It was purpose-built for scenarios where the data is sensitive and the stakes are high — banking, energy, health, and open finance.

Standard OAuth 2.0 flows were designed for social login and low-risk delegation. FAPI closes the security gaps that matter for financial data: token theft, authorization code interception, request tampering, and phishing. Regulatory frameworks around the world — including Australia's Consumer Data Right, Brazil Open Finance, and UK Open Banking — either mandate or strongly reference FAPI compliance.

**Fiskil's Data Provider implements FAPI 2.0 natively.** When you connect your Resource Server to Fiskil, every authorization flow, token exchange, and API call is automatically protected by the full FAPI security profile. Your engineering team focuses on exposing data; Fiskil handles the security infrastructure.

***

The FAPI 2.0 Protocol Stack [#the-fapi-20-protocol-stack]

FAPI 2.0 is not a standalone protocol — it's a **security profile** that constrains and hardens OAuth 2.0 and OpenID Connect. Think of it as a strict set of rules layered on top of existing standards. Here's how the layers compose:

<ProtocolStack />

<Callout type="info">
  **Key insight:** Fiskil owns every layer of the security stack above your Resource Server. You implement a standard REST API and validate JWTs — Fiskil handles the FAPI-specific complexity: pushed authorization requests, sender-constrained tokens, client certificate management, and consent compliance.
</Callout>

System Architecture [#system-architecture]

The diagram below shows how Fiskil sits between Data Recipients and your Resource Server, managing the full FAPI security layer.

<ArchitectureDiagram />

***

FAPI 2.0 Security Mechanisms [#fapi-20-security-mechanisms]

Security Profile (Base Requirements) [#security-profile-base-requirements]

The FAPI 2.0 Security Profile mandates the following mechanisms for all confidential clients. Each addresses a specific attack vector in financial data sharing.

| Mechanism                                     | Threat Mitigated                                                          | Fiskil Implementation                                                                                                                                                                                |
| --------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PAR** (Pushed Authorization Requests)       | Authorization parameter tampering, phishing via manipulated redirect URIs | All authorization requests are submitted server-to-server to the `/par` endpoint before the user is redirected. The browser only sees an opaque `request_uri` — no sensitive parameters are exposed. |
| **Sender-constrained tokens via mTLS**        | Token theft, impersonation, man-in-the-middle attacks                     | Fiskil binds access tokens to the client's X.509 certificate. Tokens are unusable without the corresponding private key. Certificate management is handled by Fiskil for registered Data Recipients. |
| **Sender-constrained tokens via DPoP**        | Token exfiltration and replay                                             | An alternative to mTLS-based sender constraining for confidential clients. Clients include a signed proof JWT with each request, binding the token to a specific key pair.                           |
| **PKCE** (Proof Key for Code Exchange)        | Authorization code interception                                           | Every authorization flow uses PKCE with the `S256` challenge method. The authorization code is bound to the original client and cannot be exchanged by an attacker.                                  |
| **`private_key_jwt`** (Client Authentication) | Client secret leakage, credential stuffing                                | Clients authenticate to the token endpoint using a JWT signed with their private key. No shared secrets are transmitted over the network.                                                            |
| **Issuer identification**                     | Authorization server mix-up attacks                                       | The `iss` parameter is included in authorization responses, allowing Data Recipients to verify which authorization server issued the response.                                                       |

Message Signing Profile (Ecosystem Requirements) [#message-signing-profile-ecosystem-requirements]

The FAPI 2.0 Message Signing profile is a separate conformance profile that adds non-repudiation to the authorization exchange. Fiskil supports Message Signing where required by an ecosystem.

| Mechanism                                             | Threat Mitigated                          | Fiskil Implementation                                                                                                                                      |
| ----------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **JAR** (JWT-Secured Authorization Request, RFC 9101) | Parameter injection, request modification | Authorization request parameters are packaged as a signed JWT (using PS256), ensuring the authorization server processes exactly what the client intended. |
| **JARM** (JWT Secured Authorization Response Mode)    | Authorization response tampering          | Authorization responses are returned as signed JWTs rather than plain URL parameters. Data Recipients can verify response integrity and authenticity.      |

***

Authorization Flow [#authorization-flow]

The following sequence shows how Fiskil orchestrates a FAPI 2.0 authorization flow between a Data Recipient (third-party application), the Fiskil Data Provider (authorization server), and your Resource Server.

<Mermaid
  chart="sequenceDiagram
    participant DR as Data Recipient
    participant F as Fiskil Data Provider
    participant U as User (Browser)
    participant RS as Your Resource Server

    Note over DR,F: 1. Pushed Authorization Request
    DR->>F: POST /connect/par (private_key_jwt)
    F-->>DR: request_uri

    Note over DR,U: 2. User Redirect
    DR->>U: Redirect to /connect/authorize?request_uri=...&client_id=...
    U->>F: Authorization request (no sensitive params in URL)

    Note over F,RS: 3. Authentication & Consent
    F->>RS: Fetch account list (JWT-authenticated)
    RS-->>F: Customer accounts
    F->>U: Present consent screen
    U->>F: Approve data sharing

    Note over F,DR: 4. Authorization Code
    F->>U: Redirect with authorization code + iss parameter
    U->>DR: Authorization code (PKCE-bound)

    Note over DR,F: 5. Token Exchange
    DR->>F: POST /connect/token (code + PKCE verifier + private_key_jwt)
    F-->>DR: Sender-constrained access token (mTLS/DPoP) + ID token

    Note over DR,RS: 6. Data Access
    DR->>F: API request with bound access token
    F->>F: Validate token binding + consent scope
    F->>RS: Forward request (short-lived JWT)
    RS-->>F: Customer data
    F-->>DR: Data response"
/>

<Steps>
  <Step title="Pushed Authorization Request">
    The Data Recipient submits authorization parameters directly to Fiskil's `/par` endpoint using `private_key_jwt` authentication. Fiskil validates the client identity, stores the request, and returns an opaque `request_uri`.

    **Data Recipient → Fiskil** (server-to-server)
  </Step>

  <Step title="User Redirect to Authorization">
    The Data Recipient redirects the user's browser to Fiskil's authorization endpoint with only the `request_uri` and `client_id`. No sensitive parameters are visible in the URL.

    **Data Recipient → Browser → Fiskil**
  </Step>

  <Step title="Authentication & Consent">
    Fiskil authenticates the end user (via your identity verification integration), presents branded consent screens showing the requested scopes and data, and captures the user's approval. Fiskil calls your Resource Server to fetch account lists for the consent screen.

    **User ↔ Fiskil**, **Fiskil → Your Resource Server**
  </Step>

  <Step title="Authorization Code Issued">
    Fiskil redirects the user back to the Data Recipient with a one-time authorization code and the `iss` parameter identifying the authorization server. The code is bound to the PKCE challenge submitted in step 1. When Message Signing is enabled, the response is returned as a signed JWT via JARM.

    **Fiskil → Browser → Data Recipient**
  </Step>

  <Step title="Token Exchange">
    The Data Recipient exchanges the authorization code at Fiskil's token endpoint, authenticating with `private_key_jwt` and presenting the PKCE verifier. Fiskil issues a **sender-constrained access token** (bound via mTLS certificate or DPoP key) and an ID token.

    **Data Recipient → Fiskil** (mTLS / DPoP bound)
  </Step>

  <Step title="Data Access">
    The Data Recipient presents the sender-constrained access token to Fiskil's data sharing endpoints. Fiskil validates the token binding (mTLS certificate thumbprint or DPoP proof), checks consent scope, and calls your Resource Server with a short-lived JWT to fetch the data.

    **Data Recipient → Fiskil → Your Resource Server**
  </Step>
</Steps>

<Callout type="info">
  **Your integration point:** Steps 3 and 6 are where Fiskil calls your Resource Server. You validate the Fiskil-issued JWT (using your JWKS endpoint) and return the requested data. Everything else — PAR, PKCE, mTLS, token binding, consent management — is handled by Fiskil.
</Callout>

***

What You Implement vs. What Fiskil Handles [#what-you-implement-vs-what-fiskil-handles]

<Cards>
  <Card title="Fiskil Manages" icon={<ShieldCheck />}>
    FAPI 2.0 authorization server, PAR endpoint, token endpoint, mTLS termination, DPoP validation, PKCE enforcement, issuer identification, consent screens, consent lifecycle, audit trails, Data Recipient onboarding, certificate management, JWKS hosting, `x-fapi-interaction-id` correlation, and regulatory reporting. When Message Signing is required: JAR validation and JARM signing.
  </Card>

  <Card title="You Build" icon={<Code />}>
    A Resource Server that exposes customer data endpoints and validates Fiskil-issued JWTs using your JWKS endpoint. Three authentication endpoints (`/customer/search`, `/customer/{id}`, `/customer/{id}/accounts`) plus your data APIs. Optionally, an IP allow-list for Fiskil's egress IPs.
  </Card>
</Cards>

***

Token Security in Depth [#token-security-in-depth]

Token theft is the primary attack vector in API-based data sharing. FAPI 2.0 addresses this through **sender-constrained tokens** — tokens that are cryptographically bound to the client that requested them, making stolen tokens useless to an attacker.

mTLS Certificate Binding [#mtls-certificate-binding]

When a Data Recipient authenticates with mutual TLS, Fiskil records the SHA-256 thumbprint of the client's X.509 certificate in the `cnf` (confirmation) claim of the access token. On every subsequent API call, Fiskil verifies that the presenting client's certificate matches the thumbprint embedded in the token. If the certificate doesn't match, the request is rejected — even if the token itself is valid.

```json
{
  "iss": "https://cdr.acme-bank.fiskil.com",
  "sub": "client_abc123",
  "scope": "accounts:read balances:read",
  "exp": 1700000000,
  "cnf": {
    "x5t#S256": "hL2FQIO7Yb...certificate-thumbprint"
  }
}
```

DPoP (Demonstration of Proof-of-Possession) [#dpop-demonstration-of-proof-of-possession]

For confidential clients that cannot use mTLS (environments without client certificate infrastructure), Fiskil supports DPoP as an alternative sender-constraining mechanism. The client generates an ephemeral key pair and includes a signed proof JWT in the `DPoP` header of each request. The access token includes a `jkt` (JWK Thumbprint) confirmation claim tying it to the client's public key.

```http
POST /connect/token HTTP/2
Host: secure.acme-bank.fiskil.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0Iiw...

grant_type=authorization_code
&code=auth_code_here
&code_verifier=pkce_verifier
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJ...
```

***

FAPI Headers and Request Correlation [#fapi-headers-and-request-correlation]

Fiskil supports the standard FAPI interaction headers across all API surfaces, providing end-to-end traceability for every request in the data sharing chain.

| Header                       | Direction          | Purpose                                                                                                                                                             |
| ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-fapi-interaction-id`      | Request & Response | UUID correlation ID that flows from the Data Recipient through Fiskil to your Resource Server and back. Enables end-to-end request tracing across all participants. |
| `x-fapi-auth-date`           | Request            | Timestamp of the user's last authentication event. Used by the authorization server to evaluate step-up authentication requirements.                                |
| `x-fapi-customer-ip-address` | Request            | The end user's IP address. Forwarded for fraud detection and audit purposes, supporting risk-based access decisions.                                                |

***

Standard OAuth 2.0 vs. FAPI 2.0 [#standard-oauth-20-vs-fapi-20]

To understand the value FAPI adds, it helps to contrast it with a standard OAuth 2.0 implementation.

| Aspect                 | Standard OAuth 2.0                            | FAPI 2.0 (Fiskil)                                                                             |
| ---------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Authorization request  | Parameters in URL query string                | Parameters pushed server-to-server via PAR; browser sees only `request_uri`                   |
| Client authentication  | `client_secret_post` or `client_secret_basic` | `private_key_jwt` or `tls_client_auth` — no shared secrets                                    |
| Token binding          | Bearer tokens (usable by anyone who has them) | Sender-constrained tokens (mTLS or DPoP bound)                                                |
| Auth code protection   | Optional PKCE                                 | Mandatory PKCE with S256                                                                      |
| Authorization response | Plain URL parameters                          | Includes `iss` parameter for server identification. With Message Signing: signed JWT via JARM |
| Transport security     | TLS (server-authenticated)                    | TLS with optional mutual authentication (mTLS)                                                |
| Request tracing        | No standard                                   | `x-fapi-interaction-id` end-to-end correlation                                                |

***

FAPI 2.0 Message Signing [#fapi-20-message-signing]

The FAPI 2.0 specification defines two distinct conformance profiles: the **Security Profile** and the **Message Signing** profile. The Security Profile (covered in the sections above) handles authorization flow hardening, token binding, and client authentication. The Message Signing profile adds a separate layer of non-repudiation — cryptographic proof that a specific message was sent by a specific party and has not been tampered with.

How It Works [#how-it-works]

Message Signing uses two complementary mechanisms. **JAR (JWT-Secured Authorization Request, RFC 9101)** requires that authorization request parameters are packaged as a signed JWT before submission. This ensures the authorization server processes exactly what the client intended — no parameter can be added, removed, or modified in transit. **JARM (JWT-Secured Authorization Response Mode)** applies the same principle in reverse: authorization responses are returned as signed JWTs, allowing the client to verify the response came from the legitimate authorization server and wasn't intercepted or altered.

Together, JAR and JARM create a **signed message chain** across the entire authorization exchange. This is particularly important in open finance, where regulatory frameworks may require audit evidence that both parties in a data sharing arrangement can prove exactly what was requested and what was authorized.

<Cards>
  <Card title="JAR — Request Signing" icon={<ArrowUp />}>
    Authorization request parameters are signed by the Data Recipient using their private key (PS256). Fiskil validates the signature against the Data Recipient's registered JWKS before processing the request. Prevents request parameter injection and provides non-repudiation of the authorization request.
  </Card>

  <Card title="JARM — Response Signing" icon={<ArrowDown />}>
    Authorization responses are signed by Fiskil using ES256. Data Recipients validate the signature against Fiskil's published JWKS. Prevents authorization response tampering and provides cryptographic proof of the authorization decision.
  </Card>
</Cards>

<Callout type="info">
  Fiskil supports both the Security Profile and Message Signing profile. JAR and JARM are enabled by default for all Data Provider instances. Data Recipients that require Message Signing conformance can rely on Fiskil's authorization server to handle both request validation and response signing without additional configuration on your Resource Server.
</Callout>

***

Discovery and Well-Known Endpoints [#discovery-and-well-known-endpoints]

Fiskil publishes standard OpenID Connect Discovery metadata at the `/.well-known/openid-configuration` endpoint for each Data Provider instance. Data Recipients use this to automatically configure their integration without hardcoding endpoints.

The metadata below is annotated to distinguish base Security Profile fields from Message Signing fields.

```json
{
  "issuer": "https://public.acme-bank.prod.provider.fiskil.com",
  "authorization_endpoint": "https://public.acme-bank.prod.provider.fiskil.com/connect/authorize",
  "token_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/connect/token",
  "introspection_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/connect/introspect",
  "revocation_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/revoke",
  "userinfo_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/userinfo",
  "registration_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/connect/register",
  "jwks_uri": "https://public.acme-bank.prod.provider.fiskil.com/jwks",
  "pushed_authorization_request_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/connect/par"
}
```

**Security Profile fields:**

```json
{
  "require_pushed_authorization_requests": true,
  "tls_client_certificate_bound_access_tokens": true,
  "authorization_response_iss_parameter_supported": true,
  "code_challenge_methods_supported": ["S256"],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "subject_types_supported": ["pairwise"],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "tls_client_auth",
    "self_signed_tls_client_auth"
  ],
  "token_endpoint_auth_signing_alg_values_supported": ["ES256", "PS256"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "dpop_signing_alg_values_supported": ["ES256", "PS256"],
  "claims_parameter_supported": true,
  "scopes_supported": ["openid", "profile", "accounts:read", "..."],
  "claims_supported": [
    "name", "given_name", "family_name", "sharing_duration",
    "iss", "sub", "aud", "acr", "exp", "iat", "nonce",
    "auth_time", "updated_at"
  ]
}
```

**Message Signing profile fields** (present when ecosystem requires JAR/JARM):

```json
{
  "response_modes_supported": ["jwt"],
  "require_signed_request_object": true,
  "request_object_signing_alg_values_supported": ["PS256", "ES256"],
  "authorization_signing_alg_values_supported": ["ES256", "PS256"]
}
```

<Callout type="info">
  Each Data Provider instance has its own discovery endpoint with instance-specific URLs. The example above shows the general structure — your actual endpoints will use your brand subdomain (e.g. `public.acme-bank.prod.provider.fiskil.com`). Message Signing fields are included when the ecosystem requires JAR and JARM conformance.
</Callout>

***

Certifications and Compliance [#certifications-and-compliance]

Fiskil undergoes independent security audits and maintains certifications that complement FAPI compliance.

<Cards>
  <Card title="SOC 2 Type 2" icon={<ShieldCheck />}>
    Independent audit of security, availability, and confidentiality controls across Fiskil's infrastructure and data handling practices.
  </Card>

  <Card title="ASAE 3150 Type 2" icon={<ClipboardCheck />}>
    Australian assurance standard for controls relevant to data handling. Required for CDR Data Holders operating in Australia.
  </Card>

  <Card title="OpenID Conformance" icon={<Lock />}>
    Fiskil's authorization server is certified against the OpenID Foundation's FAPI conformance suite.
  </Card>

  <Card title="DDoS Protection" icon={<Globe />} href="/data-holder/guides/security/firewall">
    Integrated DDoS mitigation, malicious IP blocking, and recipient throttling via Fiskil Firewall.
  </Card>
</Cards>

***

Frequently Asked Questions [#frequently-asked-questions]

<AccordionGroup>
  <Accordion title="Do I need to implement mTLS on my Resource Server?">
    No. mTLS is enforced between Data Recipients and Fiskil's authorization server. Fiskil authenticates to your Resource Server using signed JWTs (validated via JWKS). You can optionally add IP allow-listing for Fiskil's egress IPs as an additional security layer.
  </Accordion>

  <Accordion title="Which sender-constraining mechanism should Data Recipients use?">
    Fiskil supports both mTLS and DPoP for confidential clients. mTLS is required for regulatory frameworks like Australia's CDR. DPoP is available for confidential client environments where client certificate infrastructure is impractical. Fiskil's onboarding process helps Data Recipients choose the right mechanism for their use case.
  </Accordion>

  <Accordion title="Does Fiskil support FAPI 1.0 Advanced?">
    Yes. Fiskil supports FAPI 1.0 Advanced Profile for existing implementations in ecosystems that require it. FAPI 2.0 is the default for new integrations and is the successor profile recommended by the OpenID Foundation. Fiskil manages the migration path for customers transitioning between versions.
  </Accordion>

  <Accordion title="How does FAPI interact with different data standards (CDR, Open Finance)?">
    FAPI defines the security layer — how authorization, authentication, and token binding work. Data standards like CDR and Open Finance define the data model and API contracts. Fiskil implements both layers: the FAPI security profile at the authorization server level, and the standard-specific API schemas at the data sharing layer. Your Resource Server implements the data endpoints for your chosen standard.
  </Accordion>

  <Accordion title="Can I use Fiskil for non-regulated data sharing?">
    Yes. Fiskil's Bring Your Own Data (BYOD) mode lets you share any dataset through the same FAPI-secured infrastructure. Even when regulatory compliance isn't required, the security benefits of FAPI (sender-constrained tokens, PAR, PKCE) protect your data and your customers.
  </Accordion>

  <Accordion title="How does this compare to building with Auth0 or Okta?">
    General-purpose identity platforms like Auth0 and Okta provide OAuth 2.0 and OpenID Connect building blocks. FAPI compliance requires significant additional configuration: enabling PAR, configuring mTLS termination, implementing sender-constrained tokens, managing Data Recipient certificates, and building consent workflows. Fiskil provides all of this as a managed service, purpose-built for open finance data sharing — no assembly required.
  </Accordion>
</AccordionGroup>

***

Resources [#resources]

<Cards>
  <Card title="Authentication Guide" href="/data-holder/guides/build/jwt-security">
    Configure token validation and JWKS for your Resource Server.
  </Card>

  <Card title="Integration Quickstart" href="/data-holder/guides/get-started/quickstart">
    Step-by-step guide to building your Fiskil integration.
  </Card>

  <Card title="OpenID FAPI Specification" href="https://openid.net/wg/fapi/">
    Official FAPI working group documentation from the OpenID Foundation.
  </Card>
</Cards>


---

# Firewall (/data-holder/guides/security/firewall)

How Fiskil Firewall throttles data recipients, mitigates DDoS, and blocks malicious traffic before it reaches your Resource Server.



Fiskil Firewall sits in front of your Data Provider and protects your Resource Server from unbounded third-party load, denial-of-service attacks, and malicious IP traffic. Data recipients call Fiskil — not your Resource Server directly — so these controls are applied at the edge before any request is forwarded.

***

What Fiskil Firewall covers [#what-fiskil-firewall-covers]

<CardGroup cols={3}>
  <Card title="Recipient throttling" icon="gauge-high">
    Caps traffic from third-party data recipients in line with open finance standards.
  </Card>

  <Card title="DDoS protection" icon="shield">
    Mitigates volumetric and application-layer denial-of-service attacks across authorization and data-sharing endpoints.
  </Card>

  <Card title="Malicious IP blocking" icon="ban">
    Detects and blocks abusive or known-malicious IP addresses before they reach your systems.
  </Card>
</CardGroup>

When a request is rejected by the Firewall, it is **not** forwarded to your Resource Server. You do not need to implement recipient rate limiting or edge DDoS controls on your Resource Server for open finance traffic.

***

Recipient throttling [#recipient-throttling]

Fiskil automatically throttles third-party data recipients so you can plan Resource Server capacity against a predictable envelope.

Fiskil’s **default** configuration limits each data recipient to **50 TPS**. When a recipient exceeds the configured threshold, Fiskil rejects the call (typically with `429 Too Many Requests`) and does not forward it to your Resource Server.

<Callout type="info">
  Open finance traffic thresholds vary by market. Fiskil updates the Firewall configuration per environment to match the standards that apply to that deployment. Treat 50 TPS as the platform default, not a fixed global limit.
</Callout>

***

DDoS and malicious traffic [#ddos-and-malicious-traffic]

Alongside recipient throttling, Fiskil Firewall provides continuous protection against abusive traffic:

* **DDoS mitigation** across authorization and data-sharing endpoints, with automatic traffic analysis and rate limiting
* **Malicious and abusive IP detection**, blocking sources that attempt to exhaust capacity or probe your Data Provider
* **Traffic shaping** so short bursts and unreasonable usage from a single client cannot starve legitimate data sharing

This matches the edge protection described on the [Data Provider product](https://www.fiskil.com/product/data-provider) — integrated defense so your team can focus on serving consented data, not absorbing internet-scale attack traffic.

***

Capacity planning [#capacity-planning]

Use the Firewall envelope when sizing your Resource Server:

* **Per-recipient load** — under the platform default, a single data recipient should not send more than \~50 TPS of forwarded traffic; confirm the limit configured for your environment if your market differs
* **Multiple recipients** — total load can grow with the number of active recipients; size for concurrent recipients plus operational headroom
* **Performance SLAs** — response-time requirements from your open finance regime still apply to traffic that is allowed through

Monitor [metrics](/data-holder/guides/telemetry/metrics) such as Peak TPS, Average TPS, and rejections to validate real traffic against your capacity model.

***

Related [#related]

<Cards>
  <Card title="FAPI Security" href="/data-holder/guides/security/fapi">
    Financial-grade authorization, certifications, and platform security controls.
  </Card>

  <Card title="Resource Server" href="/data-holder/guides/build/resource-server">
    Build and integrate the API Fiskil calls after consent.
  </Card>

  <Card title="Metrics" href="/data-holder/guides/telemetry/metrics">
    Track TPS, invocations, and traffic-threshold rejections.
  </Card>
</Cards>


---

# Configure Microsoft (Entra ID) as a SSO Provider (/data-holder/guides/security/sso-microsoft)

Configure Single Sign-On authentication for your team to access the Fiskil Console using your existing Microsoft identity provider.



Microsoft (Entra ID) is a cloud-based identity and access management service that allows you to manage user identities and access to your applications and resources.

Prerequisites [#prerequisites]

<Check>
  You must have access to Microsoft Entra ID to configure Single Sign-On authentication with Microsoft.
</Check>

Configure Single Sign-On authentication [#configure-single-sign-on-authentication]

<Steps>
  <Step title="Create a new app registration">
    Create a new [Microsoft Identity Platform app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in Microsoft Entra ID
  </Step>

  <Step title="Configure the application">
    [Add a redirect URI](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri):

    * platform type: **Web**
    * redirect URI: `https://enablement-prod.firebaseapp.com/__/auth/handler`
  </Step>

  <Step title="Configure credentials">
    [Create a client secret](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret) in the new application. Please take note of the client secret value (not the ID) when it is first created as it will not be retrievable at a later date
  </Step>

  <Step title="Configure Fiskil Login">
    Use the Fiskil Console to [Enable SSO](/data-holder/guides/security/sso#how-to-enable-sso) by providing Client ID, Client Secret, and Directory (tenant) ID
  </Step>
</Steps>


---

# SSO Logins (/data-holder/guides/security/sso)

Enable Single Sign-On authentication for your team to access the Fiskil Console using your existing identity provider.



Single Sign-On (SSO) authentication lets your users log in to the Fiskil Console using the same credentials they use for other services.

***

Supported Providers [#supported-providers]

Fiskil supports federated identity using Microsoft Entra ID with more identity providers coming, including:

<CardGroup cols={3}>
  <Card title="Google" icon="google">
    Google Workspace and Gmail accounts
  </Card>

  <Card title="Microsoft" icon="microsoft">
    Microsoft Identity Platform and [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/)
  </Card>

  <Card title="Okta" icon="shield-check">
    Okta identity management platform
  </Card>

  <Card title="OIDC" icon="link">
    Any OIDC-compliant IdP
  </Card>

  <Card title="Custom Provider" icon="gear">
    Contact support for additional providers
  </Card>
</CardGroup>

<Info>
  Authentication with additional OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) 2.0 providers is available on request via the Fiskil team.
</Info>

***

How to Enable SSO [#how-to-enable-sso]

SSO can be configured in the [Fiskil Console](https://console.fiskil.com/data-holder/settings/sso)

<Steps>
  <Step title="Configure Your Identity Provider">
    <Card title="Configure Microsoft (Entra ID) as a SSO Provider" href="/data-holder/guides/security/sso-microsoft" icon="microsoft">
      How to configure Single Sign-On authentication for your team to access the Fiskil Console using your existing Microsoft identity provider.
    </Card>

    <Tip>
      Make note of your Client ID and Client Secret, you'll need these for the next steps.
    </Tip>
  </Step>

  <Step title="Activate SSO">
    Log in to the Fiskil Console and navigate to the [SSO menu](https://console.fiskil.com/data-holder/settings/sso). Select your identity provider
    from the list and fill out the form. You'll need to provide your client ID, client secret, and any provider-specific metadata.

    <Warning>
      Double check your SSO parameters. Incorrect configuration could lock you out of the portal. If you get stuck, contact [Fiskil Support](https://fiskil.atlassian.net/servicedesk/customer/portal/6).
    </Warning>
  </Step>

  <Step title="User Access">
    Once enabled, users attempting to log in are redirected to your identity provider. After successful authentication, they return to the Fiskil Console signed in with the role assigned to them in **Settings > Members**.
  </Step>
</Steps>

***


---

# SSO Logins (/data-api/guides/account-access/sso-login)

Enable Single Sign-On authentication for your team to access the Fiskil Console using your existing identity provider.



Single Sign-On (SSO) authentication lets your users log in to the Fiskil Console using the same credentials they use for other services.

***

import { Chrome as Google, AppWindow as Windows, ShieldCheck, Link, Settings } from 'lucide-react'

Supported Providers [#supported-providers]

Fiskil supports federated identity using Microsoft Entra ID with more identity providers coming, including:

<CardGroup cols={3}>
  <Card title="Google" icon={<Google />}>
    Google Workspace and Gmail accounts
  </Card>

  <Card title="Microsoft" icon={<Windows />}>
    Microsoft Identity Platform and [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/)
  </Card>

  <Card title="Okta" icon={<ShieldCheck />}>
    Okta identity management platform
  </Card>

  <Card title="OIDC" icon={<Link />}>
    Any OIDC-compliant IdP
  </Card>

  <Card title="Custom Provider" icon={<Settings />}>
    Contact support for additional providers
  </Card>
</CardGroup>

<Info>
  Authentication with additional OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) 2.0 providers is available on request via the Fiskil team.
</Info>

***

How to Enable SSO [#how-to-enable-sso]

SSO can be configured in the [Fiskil Console](https://console.fiskil.com/data-holder/settings/sso)

<Steps>
  <Step title="Configure Your Identity Provider">
    <Card title="Configure Microsoft (Entra ID) as a SSO Provider" href="/data-api/guides/account-access/sso-login/microsoft" icon={<Windows />}>
      How to configure Single Sign-On authentication for your team to access the Fiskil Console using your existing Microsoft identity provider.
    </Card>

    <Tip>
      Make note of your Client ID and Client Secret, you'll need these for the next steps.
    </Tip>
  </Step>

  <Step title="Activate SSO">
    Log in to the Fiskil Console and navigate to the [SSO menu](https://console.fiskil.com/data-holder/settings/sso). Select your identity provider
    from the list and fill out the form. You'll need to provide your client ID, client secret, and any provider-specific metadata.

    <Warning>
      Double check your SSO parameters. Incorrect configuration could lock you out of the portal. If you get stuck, contact [Fiskil Support](https://fiskil.atlassian.net/servicedesk/customer/portal/6).
    </Warning>
  </Step>

  <Step title="User Access">
    Once enabled, users attempting to log in are redirected to your identity provider. After successful authentication, they return to the Fiskil Console signed in with the role assigned to them in **Settings > Members**.
  </Step>
</Steps>


---

# Configure Microsoft (Entra ID) as a SSO Provider (/data-api/guides/account-access/sso-login/microsoft)

Configure Single Sign-On authentication for your team to access the Fiskil Console using your existing Microsoft identity provider.



Microsoft (Entra ID) is a cloud-based identity and access management service that allows you to manage user identities and access to your applications and resources.

Prerequisites [#prerequisites]

<Check>
  You must have access to Microsoft Entra ID to configure Single Sign-On authentication with Microsoft.
</Check>

Configure Single Sign-On authentication [#configure-single-sign-on-authentication]

<Steps>
  <Step title="Create a new app registration">
    Create a new [**Microsoft Identity Platform app registration**](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in Microsoft Entra ID
  </Step>

  <Step title="Configure the application" bulletList={true}>
    [**Add a redirect URI**](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri):

    * platform type: **Web**
    * redirect URI: `https://enablement-prod.firebaseapp.com/__/auth/handler`
  </Step>

  <Step title="Configure credentials">
    [**Create a client secret**](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret) in the new application. Please take note of the client secret value (not the ID) when it is first created as it will not be retrievable at a later date
  </Step>

  <Step title="Configure Fisil Login">
    Use the Fiskil Console to [**Enable SSO**](/docs/security/sso#how-to-enable-sso) by providing Client ID, Client Secret, and Directory (tenant) ID
  </Step>
</Steps>


---

# Requisitos de integración (/es/data-holder/api-reference/latam-chile/integration-requirements)

Requisitos funcionales y no funcionales para integrar la plataforma Data Provider de Open Finance Chile de Fiskil.



Este documento resume lo que debe hacer para integrar la plataforma Data Provider de Fiskil y construir una integración conforme a Open Finance en Chile.

***

Qué está construyendo [#qué-está-construyendo]

Al integrarse con Fiskil para el estándar de Open Finance en Chile, implementa un **Resource Server**: su API que expone datos de clientes según los requisitos regulatorios del país.

División de responsabilidades [#división-de-responsabilidades]

**Fiskil se encarga de:**

* **Servidor de autorización (OAuth2/OIDC) y gestión del consentimiento**\
  Orquestación completa del flujo de consentimiento, incluyendo captura, gestión, actualización y revocatoria.
* **Emisión, firma y validación de tokens**\
  Generación de tokens JWT firmados (RS256/PS256), gestión de claves vía JWKS y control de acceso basado en scopes.
* **Monitoreo, auditoría e informes de cumplimiento**\
  Registro de actividad (logs), trazabilidad de consentimientos y soporte a requerimientos regulatorios.
* **Gestión de terceros receptores de datos (TPPs)**\
  Registro, validación y administración de participantes dentro del ecosistema.
* **Interfaz de consentimiento conforme a estándares**\
  Experiencia de usuario para autorización alineada con principios de Open Finance (transparencia, granularidad y control).

**Usted implementa:**

* **Resource Server con endpoints de datos**\
  API segura que expone información de clientes (cuentas, balances, transacciones, etc.) conforme a los scopes autorizados.
* **Validación de autenticación y autorización de Fiskil**\
  Verificación de tokens JWT (firma, expiración, audiencia, issuer, jti) utilizando JWKS.
* **Disponibilidad, rendimiento y calidad de las APIs**\
  Cumplimiento de estándares de performance, consistencia de datos y manejo de errores para garantizar una integración confiable.

***

Requisitos previos [#requisitos-previos]

Antes de comenzar, asegúrese de contar con:

<AccordionGroup>
  <Accordion title="Cuenta Fiskil e instancias aprovisionadas">
    Acceso a la plataforma Fiskil con entornos de **Staging y Producción** configurados.

    Cada entorno es independiente y cuenta con sus propias claves, configuración y registros.

    Si aún no dispone de estos entornos, contacte a Fiskil para su aprovisionamiento.
  </Accordion>

  <Accordion title="Comprensión de las obligaciones de Open Finance en Chile">
    Como proveedor de datos bajo el marco de Open Finance en Chile, tiene obligaciones regulatorias además de la integración técnica. Familiarícese con:

    * Responsabilidades como proveedor de datos
    * Gestión del consentimiento y derechos del consumidor
    * Alcance y límites del intercambio de datos
    * Requerimientos de informes y cumplimiento
    * Normativa de privacidad y protección de datos personales
  </Accordion>

  <Accordion title="Infraestructura técnica">
    Su Resource Server debe contar con:

    * Endpoints HTTPS accesibles para Fiskil
    * Capacidad de cumplir requisitos de disponibilidad y rendimiento
    * Monitoreo y alertas operativas
    * Identificadores consistentes de clientes y cuentas (por ejemplo, RUT o IDs internos)
  </Accordion>
</AccordionGroup>

***

Requisitos funcionales [#requisitos-funcionales]

Panorama del Resource Server [#panorama-del-resource-server]

Su Resource Server es una API HTTPS a la que Fiskil llama después de que el cliente autorice el uso compartido de datos. Debe:

* Aceptar y validar tokens Bearer emitidos por Fiskil
* Devolver datos en el formato JSON esperado
* Manejar errores con códigos de estado HTTP estándar
* Admitir paginación en los endpoints de listado

Endpoints del flujo de autenticación y consentimiento [#endpoints-del-flujo-de-autenticación-y-consentimiento]

Estos endpoints se invocan durante el consentimiento del usuario para identificar clientes y mostrar sus cuentas.

<Cards>
  <Card title="Búsqueda de cliente" href="/es/data-holder/api-reference/latam-chile/customerSearch">
    Permite identificar al cliente al iniciar el flujo de consentimiento (por ejemplo, mediante correo electrónico o el SCA de la entidad financiera).
  </Card>

  <Card title="Cuentas del cliente" href="/es/data-holder/api-reference/latam-chile/listAccountsAuth">
    Devuelva la lista de cuentas entre las que el cliente puede elegir compartir datos.
  </Card>

  <Card title="Datos del cliente" href="/es/data-holder/api-reference/latam-chile/getIdentity">
    Proporcione datos de identidad del cliente para el flujo de consentimiento.
  </Card>
</Cards>

<Callout type="warn">
  Estos endpoints son críticos para el flujo de consentimiento. Deben devolver identificadores de cliente y cuenta estables que no cambien.
</Callout>

Endpoints de datos de Open Finance Chile [#endpoints-de-datos-de-open-finance-chile]

Una vez otorgado el consentimiento, Fiskil invoca su **Resource Server** para obtener los datos autorizados del cliente.

El parámetro de ruta `customer/{customerId}` es generado e incluido por Fiskil en todas las solicitudes. Este identificador es **interno al flujo entre Fiskil y el proveedor de datos** y no es expuesto a terceros.

**Endpoints obligatorios:**

| Categoría         | Endpoints                                 |
| ----------------- | ----------------------------------------- |
| **Cuentas**       | Listar cuentas, Obtener detalle de cuenta |
| **Saldos**        | Obtener saldo de la cuenta                |
| **Transacciones** | Listar transacciones de la cuenta         |
| **Clientes**      | Obtener cliente                           |

Estándares y patrones de API [#estándares-y-patrones-de-api]

**Autenticación**

Su **Resource Server** debe validar los tokens **Bearer** emitidos por Fiskil en cada solicitud.

La validación incluye la verificación de firma, expiración y claims del token mediante el endpoint JWKS correspondiente.

Consulte la sección de [**Seguridad JWT**](/es/data-holder/guides/build/jwt-security) para detalles de implementación.

```http
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Parámetro de ruta del ID de cliente**

Todos los endpoints de datos incluyen el parámetro de ruta `customer/{customerId}`.

Fiskil determina e inyecta este identificador en cada solicitud en función del **token de acceso y el consentimiento asociado**, garantizando que solo se acceda a los datos autorizados.

Ejemplos de rutas:

* `/accounts/v1/customer/{customerId}/accounts`
* `/accounts/v1/customer/{customerId}/accounts/{accountID}/balance`
* `/accounts/v1/customer/{customerId}/accounts/{accountID}/transactions`
* `/customers/v1/customer/{customerId}/pn`

**Manejo de errores**

Utilice códigos de estado HTTP estándar y respuestas de error estructuradas:

* `401` — No autenticado (JWT ausente o no válido)
* `403` — Prohibido (permisos insuficientes)
* `404` — No encontrado (el recurso no existe)

**Paginación**

Admita paginación en listados con los parámetros de consulta `page` y `pageSize`. Incluya enlaces y metadatos de paginación en las respuestas.

***

Requisitos no funcionales [#requisitos-no-funcionales]

Estos requisitos técnicos son críticos para el éxito de la integración.

<Callout type="info">
  Fiskil ofrece herramientas para ayudarle a cumplirlos, pero su Resource Server debe diseñarse teniendo en cuenta estas restricciones.
</Callout>

Estabilidad de identificadores [#estabilidad-de-identificadores]

<Callout type="warn">
  **Requisito crítico:** Los IDs de cliente y de cuenta deben ser permanentes y estables. Cambiar estos identificadores romperá consentimientos y el intercambio de datos.
</Callout>

**IDs de cliente:**

* Deben mantenerse estables en todas las sesiones e interacciones
* Deben ser únicos en su organización
* No deben reutilizarse para clientes distintos
* No deben codificar información temporal o propia de la sesión

**IDs de cuenta:**

* Deben mantenerse estables durante la vida útil de la cuenta
* Deben ser únicos en su organización
* Deben persistir aunque la cuenta se cierre o reabra
* No deben cambiar al actualizar datos de la cuenta

<Callout type="info">
  Use claves primarias internas o UUID estables. Evite números de cuenta u otros identificadores visibles para el cliente que puedan cambiar.
</Callout>

Requisitos de rendimiento [#requisitos-de-rendimiento]

Su Resource Server debería responder dentro de umbrales de tiempo razonables para una buena experiencia de usuario.

**Umbrales de tiempo de respuesta recomendados:**

| Prioridad                  | Tiempo de respuesta | Ejemplos de endpoints                 |
| -------------------------- | ------------------- | ------------------------------------- |
| **Alta**                   | 1000 ms             | Listar cuentas, Obtener cliente       |
| **Estándar**               | 1500 ms             | Detalle de cuenta, Saldo de la cuenta |
| **Operaciones de listado** | 2000 ms             | Listar transacciones de la cuenta     |

Protección de tráfico (Fiskil Firewall) [#protección-de-tráfico-fiskil-firewall]

Fiskil Firewall se sitúa frente a su Resource Server y lo protege automáticamente frente a carga ilimitada de terceros y tráfico abusivo:

* **Limitación de receptores** — el valor por defecto de Fiskil es **50 TPS** por receptor de datos. Las llamadas en exceso se rechazan (normalmente con `429 Too Many Requests`) y no se reenvían a su Resource Server
* **Mitigación DDoS** — los ataques volumétricos y de capa de aplicación se absorben en el edge de Fiskil
* **Bloqueo de IPs maliciosas** — orígenes abusivos o conocidos como maliciosos se bloquean antes de llegar a sus sistemas

Los umbrales de open finance varían según el mercado. Fiskil actualiza la configuración del Firewall por entorno para alinearla con los estándares aplicables a ese despliegue. Para detalles de planificación de capacidad, vea [Firewall](/es/data-holder/guides/security/firewall).

Requisitos de disponibilidad [#requisitos-de-disponibilidad]

**Disponibilidad recomendada:** 99,5 % mensual

Diseñe su infraestructura para alta disponibilidad:

* Mecanismos de redundancia y conmutación por error
* Ventanas de mantenimiento planificadas con cuidado
* Monitoreo continuo de tiempo activo
* Procedimientos de respuesta ante incidentes

Estándares de calidad de datos [#estándares-de-calidad-de-datos]

<Callout type="warn">
  Debe adoptar medidas razonables para que los datos sean exactos, actualizados y completos.
</Callout>

**Requisitos:**

* Los datos de cuentas deben estar al día y reflejar el estado real
* Los datos de clientes deben estar alineados con sus sistemas de origen
* Transacciones y saldos deben ser exactos y completos
* Los procesos de calidad de datos deben estar documentados

***

Lista de implementación [#lista-de-implementación]

Recorrido de integración de punta a punta: cada paso resume el objetivo y las acciones concretas.

<Steps>
  <Step title="Aprovisionar infraestructura del Resource Server">
    Exponga endpoints **HTTPS** accesibles para Fiskil, con escalado y redundancia adecuados.

    * Poner en marcha URLs alcanzables desde Fiskil con TLS válido
    * Dimensionar escalado y redundancia para la carga esperada

    <Callout type="info">
      Comience en **Staging** y valide antes de pasar a **producción**.
    </Callout>
  </Step>

  <Step title="Implementar endpoints del flujo de consentimiento">
    Exponga búsqueda, selección de cuentas e identidad para el consentimiento.

    * **Búsqueda de cliente** (por correo, id o resultante del SCA de la entidad)
    * **Cuentas del cliente** (lista para selección)
    * **Datos del cliente** (identidad)
    * Garantizar **identificadores estables** de cliente y cuenta en las respuestas
  </Step>

  <Step title="Implementar endpoints de datos compartidos">
    Implemente los endpoints de datos obligatorios en el orden de prioridad indicado.

    * **Cuentas:** listar y detalle
    * **Saldos:** saldo de la cuenta
    * **Transacciones:** listado
    * **Clientes:** obtener cliente
    * Priorizar cuentas y saldos antes que transacciones y cliente
  </Step>

  <Step title="Verificar estabilidad de identificadores">
    Confirme que los IDs de cliente y cuenta son permanentes y no rotan con el uso cotidiano.

    * Revisar la estrategia de generación de IDs
    * Probar que persisten entre sesiones y actualizaciones del sistema
    * Documentar el esquema de identificadores

    <Callout type="warn">
      **Crítico:** los IDs inestables rompen consentimientos activos y generan fallos en el intercambio de datos.
    </Callout>
  </Step>

  <Step title="Implementar manejo de errores">
    Devuelva códigos HTTP y cuerpos de error alineados con lo que consume Fiskil.

    * `401` — no autenticado (JWT ausente o no válido)
    * `403` — prohibido (permisos insuficientes)
    * `404` — recurso no encontrado
    * Incluir **respuestas de error estructuradas** en cada caso
  </Step>

  <Step title="Optimizar el rendimiento">
    Cumpla objetivos de latencia y capacidad frente al tráfico esperado.

    * Medir y mejorar el tiempo de respuesta en **percentil 95**
    * Optimizar consultas a base de datos y uso de **caché**
    * Definir **timeouts** acordes al SLA
    * Ejecutar **pruebas de carga** representativas del volumen previsto
  </Step>

  <Step title="Monitoreo y alertas">
    Supervise disponibilidad, latencia y errores con alertas operativas.

    * **Tiempo activo** (disponibilidad)
    * **Métricas** de tiempo de respuesta
    * **Tasa de errores**
    * **Alertas** ante degradaciones e incidentes

    <Callout type="info">
      Use la telemetría de Fiskil: [Registros](/es/data-holder/guides/telemetry/logs) y [Métricas](/es/data-holder/guides/telemetry/metrics).
    </Callout>
  </Step>

  <Step title="Pruebas de extremo a extremo">
    Valide el flujo completo de consentimiento y datos antes del corte a producción.

    * Ejecutar pruebas con las **herramientas de Fiskil**
    * Cubrir **todos los endpoints** con escenarios distintos
    * Verificar **manejo de errores** y casos límite
    * Comprobar **rendimiento bajo carga**

    <Callout type="info">
      Guía detallada: [Visión general de pruebas](/es/data-holder/guides/testing).
    </Callout>
  </Step>
</Steps>

***

Recursos y próximos pasos [#recursos-y-próximos-pasos]

<Cards>
  <Card title="Guía de inicio rápido" href="/es/data-holder/guides/get-started/quickstart">
    Tutorial paso a paso para su primera integración con Fiskil.
  </Card>

  <Card title="Seguridad JWT" href="/es/data-holder/guides/build/jwt-security">
    Detalle de validación de tokens y configuración JWKS.
  </Card>

  <Card title="Herramientas de prueba" href="/es/data-holder/guides/testing">
    Recursos para probar su integración.
  </Card>
</Cards>

***

¿Necesita ayuda? [#necesita-ayuda]

<Callout type="info">
  Fiskil ofrece soporte durante toda la integración. Contacte a su equipo de cuenta o use la [Consola de Fiskil](https://console.fiskil.com) para asistencia técnica.
</Callout>


---

# Requisitos de integración (/es/data-holder/api-reference/latam-colombia/integration-requirements)

Requisitos funcionales y no funcionales para integrar la plataforma Data Provider de Fiskil en el contexto de Open Finance en Colombia.



Este documento describe los lineamientos técnicos y operativos necesarios para integrar la plataforma Data Provider de Fiskil, permitiendo a la entidad habilitar el intercambio seguro de datos conforme a los principios de Open Finance y los requisitos regulatorios aplicables en Colombia.

***

Qué está construyendo [#qué-está-construyendo]

Al integrarse con Fiskil, la entidad implementa un **Resource Server**, es decir, una API segura que expone datos de clientes de forma controlada y basada en consentimiento.

Fiskil se encarga de la gestión de autorización, consentimiento y emisión de tokens (OAuth2/OIDC), mientras que la entidad es responsable de exponer los datos a través de sus endpoints, cumpliendo con estándares de seguridad como FAPI 2.0 y las regulaciones locales.

División de responsabilidades [#división-de-responsabilidades]

**Fiskil se encarga de:**

* **Servidor de autorización (OAuth2/OIDC) y gestión del consentimiento**\
  Orquestación completa del flujo de consentimiento, incluyendo captura, gestión, actualización y revocatoria.
* **Emisión, firma y validación de tokens**\
  Generación de tokens JWT firmados (RS256/PS256), gestión de claves vía JWKS y control de acceso basado en scopes.
* **Monitoreo, auditoría e informes de cumplimiento**\
  Registro de actividad (logs), trazabilidad de consentimientos y soporte a requerimientos regulatorios.
* **Gestión de terceros receptores de datos (TPPs)**\
  Registro, validación y administración de participantes dentro del ecosistema.
* **Interfaz de consentimiento conforme a estándares**\
  Experiencia de usuario para autorización alineada con principios de Open Finance (transparencia, granularidad y control).

**Usted implementa:**

* **Resource Server con endpoints de datos**\
  API segura que expone información de clientes (cuentas, balances, transacciones, etc.) conforme a los scopes autorizados.
* **Validación de autenticación y autorización de Fiskil**\
  Verificación de tokens JWT (firma, expiración, audiencia, issuer, jti) utilizando JWKS.
* **Disponibilidad, rendimiento y calidad de las APIs**\
  Cumplimiento de estándares de performance, consistencia de datos y manejo de errores para garantizar una integración confiable.

***

Requisitos previos [#requisitos-previos]

Antes de comenzar, asegúrese de contar con:

<AccordionGroup>
  <Accordion title="Cuenta Fiskil e instancias aprovisionadas">
    Acceso a la plataforma Fiskil con entornos de **Staging y Producción** configurados.

    Cada entorno es independiente y cuenta con sus propias claves, configuración y registros.

    Si aún no dispone de estos entornos, contacte a Fiskil para su aprovisionamiento.
  </Accordion>

  <Accordion title="Comprensión de las obligaciones de Open Finance en Colombia">
    Como proveedor de datos bajo el marco de Open Finance en Colombia, tiene obligaciones regulatorias además de la integración técnica. Familiarícese con:

    * Responsabilidades como proveedor de datos
    * Gestión del consentimiento y derechos del consumidor (Ley 1581 de 2012 – Habeas Data)
    * Alcance y límites del intercambio de datos
    * Requerimientos de cumplimiento ante la Superintendencia Financiera de Colombia
    * Normativa de privacidad y protección de datos
  </Accordion>

  <Accordion title="Infraestructura técnica">
    Su Resource Server debe contar con:

    * Endpoints HTTPS accesibles para Fiskil
    * Capacidad de cumplir requisitos de disponibilidad y rendimiento
    * Monitoreo y alertas operativas
    * Identificadores consistentes de clientes y cuentas (por ejemplo, cédula o IDs internos)
  </Accordion>

  <Callout type="info" title="🇨🇴 Nota sobre regulación y estándares aplicables">
    El marco regulatorio y los estándares técnicos de Open Finance en Colombia se encuentran actualmente en proceso de definición por parte de la Unidad de Regulación Financiera (URF) y la Superintendencia Financiera de Colombia (SFC).

    Mientras estos lineamientos son formalmente establecidos, este perfil de integración adopta como referencia estándares internacionales consolidados, incluyendo el Open Banking Implementation Entity (OBIE) del Reino Unido y el Consumer Data Right (CDR) de Australia.

    Estos estándares sirven como base para la implementación de flujos de consentimiento, modelos de seguridad y estructuras de APIs, permitiendo asegurar interoperabilidad, cumplimiento y alineación con mejores prácticas globales, mientras evoluciona el marco normativo local.
  </Callout>
</AccordionGroup>

***

Requisitos funcionales [#requisitos-funcionales]

Panorama del Resource Server [#panorama-del-resource-server]

Su **Resource Server** es una API HTTPS que Fiskil consume una vez el cliente ha autorizado el intercambio de datos. Debe:

* Aceptar y validar tokens **Bearer** emitidos por Fiskil
* Devolver respuestas en el formato **JSON** esperado
* Manejar errores mediante códigos de estado **HTTP** estándar
* Soportar paginación en los endpoints de listado

Endpoints del flujo de autenticación y consentimiento [#endpoints-del-flujo-de-autenticación-y-consentimiento]

Estos endpoints se invocan durante el flujo de consentimiento para identificar al cliente y exponer las cuentas disponibles para autorización.

<Cards>
  <Card title="Búsqueda de cliente" href="/es/data-holder/api-reference/latam-colombia/customerSearch">
    Permite identificar al cliente al iniciar el flujo de consentimiento (por ejemplo, mediante correo electrónico o el SCA de la entidad financiera).
  </Card>

  <Card title="Cuentas del cliente" href="/es/data-holder/api-reference/latam-colombia/listAccountsAuth">
    Devuelve las cuentas elegibles que el cliente puede seleccionar para compartir, según el alcance del consentimiento.
  </Card>

  <Card title="Datos del cliente" href="/es/data-holder/api-reference/latam-colombia/getIdentity">
    Proporciona información de identidad del cliente requerida para el flujo de consentimiento.
  </Card>
</Cards>

<Callout type="warn">
  Estos endpoints son críticos para el flujo de consentimiento. Deben devolver identificadores de cliente y cuenta **consistentes y persistentes**, que no cambien en el tiempo.
</Callout>

Endpoints de datos de Open Finance Colombia [#endpoints-de-datos-de-open-finance-colombia]

Una vez otorgado el consentimiento, Fiskil invoca su **Resource Server** para obtener los datos autorizados del cliente.

El parámetro de ruta `customer/{customerId}` es generado e incluido por Fiskil en todas las solicitudes. Este identificador es **interno al flujo entre Fiskil y el proveedor de datos** y no es expuesto a terceros.

**Endpoints obligatorios:**

| Categoría         | Endpoints                                 |
| ----------------- | ----------------------------------------- |
| **Cuentas**       | Listar cuentas, Obtener detalle de cuenta |
| **Saldos**        | Obtener saldo de la cuenta                |
| **Transacciones** | Listar transacciones de la cuenta         |
| **Clientes**      | Obtener cliente                           |

Estándares y patrones de API [#estándares-y-patrones-de-api]

**Autenticación**

Su **Resource Server** debe validar los tokens **Bearer** emitidos por Fiskil en cada solicitud.

La validación incluye la verificación de firma, expiración y claims del token mediante el endpoint JWKS correspondiente.

Consulte la sección de [**Seguridad JWT**](/es/data-holder/guides/build/jwt-security) para detalles de implementación.

```http
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Parámetro de ruta del ID de cliente**

Todos los endpoints de datos incluyen el parámetro de ruta `customer/{customerId}`.

Fiskil determina e inyecta este identificador en cada solicitud en función del **token de acceso y el consentimiento asociado**, garantizando que solo se acceda a los datos autorizados.

Ejemplos de rutas:

* `/accounts/v1/customer/{customerId}/accounts`
* `/accounts/v1/customer/{customerId}/accounts/{accountID}/balance`
* `/accounts/v1/customer/{customerId}/accounts/{accountID}/transactions`
* `/customers/v1/customer/{customerId}/pn`

**Manejo de errores**

Utilice códigos de estado HTTP estándar y respuestas de error estructuradas:

* `401` — No autenticado (JWT ausente o no válido)
* `403` — Prohibido (permisos insuficientes)
* `404` — No encontrado (el recurso no existe)

**Paginación**

Admita paginación en listados con los parámetros de consulta `page` y `pageSize`. Incluya enlaces y metadatos de paginación en las respuestas.

***

Requisitos no funcionales [#requisitos-no-funcionales]

Estos requisitos técnicos son críticos para el éxito de la integración.

<Callout type="info">
  Fiskil ofrece herramientas para ayudarle a cumplirlos, pero su Resource Server debe diseñarse teniendo en cuenta estas restricciones.
</Callout>

Estabilidad de identificadores [#estabilidad-de-identificadores]

<Callout type="warn">
  **Requisito crítico:** Los IDs de cliente y de cuenta deben ser permanentes y estables. Cambiar estos identificadores romperá consentimientos y el intercambio de datos.
</Callout>

**IDs de cliente:**

* Deben mantenerse estables en todas las sesiones e interacciones
* Deben ser únicos en su organización
* No deben reutilizarse para clientes distintos
* No deben codificar información temporal o propia de la sesión

**IDs de cuenta:**

* Deben mantenerse estables durante la vida útil de la cuenta
* Deben ser únicos en su organización
* Deben persistir aunque la cuenta se cierre o reabra
* No deben cambiar al actualizar datos de la cuenta

<Callout type="info">
  Use claves primarias internas o UUID estables. Evite números de cuenta u otros identificadores visibles para el cliente que puedan cambiar.
</Callout>

Requisitos de rendimiento [#requisitos-de-rendimiento]

Su Resource Server debería responder dentro de umbrales de tiempo razonables para una buena experiencia de usuario.

**Umbrales de tiempo de respuesta recomendados:**

| Prioridad                  | Tiempo de respuesta | Ejemplos de endpoints                 |
| -------------------------- | ------------------- | ------------------------------------- |
| **Alta**                   | 1000 ms             | Listar cuentas, Obtener cliente       |
| **Estándar**               | 1500 ms             | Detalle de cuenta, Saldo de la cuenta |
| **Operaciones de listado** | 2000 ms             | Listar transacciones de la cuenta     |

Protección de tráfico (Fiskil Firewall) [#protección-de-tráfico-fiskil-firewall]

Fiskil Firewall se sitúa frente a su Resource Server y lo protege automáticamente frente a carga ilimitada de terceros y tráfico abusivo:

* **Limitación de receptores** — el valor por defecto de Fiskil es **50 TPS** por receptor de datos. Las llamadas en exceso se rechazan (normalmente con `429 Too Many Requests`) y no se reenvían a su Resource Server
* **Mitigación DDoS** — los ataques volumétricos y de capa de aplicación se absorben en el edge de Fiskil
* **Bloqueo de IPs maliciosas** — orígenes abusivos o conocidos como maliciosos se bloquean antes de llegar a sus sistemas

Los umbrales de open finance varían según el mercado. Fiskil actualiza la configuración del Firewall por entorno para alinearla con los estándares aplicables a ese despliegue. Para detalles de planificación de capacidad, vea [Firewall](/es/data-holder/guides/security/firewall).

Requisitos de disponibilidad [#requisitos-de-disponibilidad]

**Disponibilidad recomendada:** 99,5 % mensual

Diseñe su infraestructura para alta disponibilidad:

* Mecanismos de redundancia y conmutación por error
* Ventanas de mantenimiento planificadas con cuidado
* Monitoreo continuo de tiempo activo
* Procedimientos de respuesta ante incidentes

Estándares de calidad de datos [#estándares-de-calidad-de-datos]

<Callout type="warn">
  Debe adoptar medidas razonables para que los datos sean exactos, actualizados y completos.
</Callout>

**Requisitos:**

* Los datos de cuentas deben estar al día y reflejar el estado real
* Los datos de clientes deben estar alineados con sus sistemas de origen
* Transacciones y saldos deben ser exactos y completos
* Los procesos de calidad de datos deben estar documentados

***

Lista de implementación [#lista-de-implementación]

Recorrido de integración de punta a punta: cada paso resume el objetivo y las acciones concretas.

<Steps>
  <Step title="Aprovisionar infraestructura del Resource Server">
    Exponga endpoints **HTTPS** accesibles para Fiskil, con escalado y redundancia adecuados.

    * Poner en marcha URLs alcanzables desde Fiskil con TLS válido
    * Dimensionar escalado y redundancia para la carga esperada

    <Callout type="info">
      Comience en **Staging** y valide antes de pasar a **producción**.
    </Callout>
  </Step>

  <Step title="Implementar endpoints del flujo de consentimiento">
    Exponga búsqueda, selección de cuentas e identidad para el consentimiento.

    * **Búsqueda de cliente** (por correo, id o resultante del SCA de la entidad)
    * **Cuentas del cliente** (lista para selección)
    * **Datos del cliente** (identidad)
    * Garantizar **identificadores estables** de cliente y cuenta en las respuestas
  </Step>

  <Step title="Implementar endpoints de datos compartidos">
    Implemente los endpoints de datos obligatorios en el orden de prioridad indicado.

    * **Cuentas:** listar y detalle
    * **Saldos:** saldo de la cuenta
    * **Transacciones:** listado
    * **Clientes:** obtener cliente
    * Priorizar cuentas y saldos antes que transacciones y cliente
  </Step>

  <Step title="Verificar estabilidad de identificadores">
    Confirme que los IDs de cliente y cuenta son permanentes y no rotan con el uso cotidiano.

    * Revisar la estrategia de generación de IDs
    * Probar que persisten entre sesiones y actualizaciones del sistema
    * Documentar el esquema de identificadores

    <Callout type="warn">
      **Crítico:** los IDs inestables rompen consentimientos activos y generan fallos en el intercambio de datos.
    </Callout>
  </Step>

  <Step title="Implementar manejo de errores">
    Devuelva códigos HTTP y cuerpos de error alineados con lo que consume Fiskil.

    * `401` — no autenticado (JWT ausente o no válido)
    * `403` — prohibido (permisos insuficientes)
    * `404` — recurso no encontrado
    * Incluir **respuestas de error estructuradas** en cada caso
  </Step>

  <Step title="Optimizar el rendimiento">
    Cumpla objetivos de latencia y capacidad frente al tráfico esperado.

    * Medir y mejorar el tiempo de respuesta en **percentil 95**
    * Optimizar consultas a base de datos y uso de **caché**
    * Definir **timeouts** acordes al SLA
    * Ejecutar **pruebas de carga** representativas del volumen previsto
  </Step>

  <Step title="Monitoreo y alertas">
    Supervise disponibilidad, latencia y errores con alertas operativas.

    * **Tiempo activo** (disponibilidad)
    * **Métricas** de tiempo de respuesta
    * **Tasa de errores**
    * **Alertas** ante degradaciones e incidentes

    <Callout type="info">
      Use la telemetría de Fiskil: [Registros](/es/data-holder/guides/telemetry/logs) y [Métricas](/es/data-holder/guides/telemetry/metrics).
    </Callout>
  </Step>

  <Step title="Pruebas de extremo a extremo">
    Valide el flujo completo de consentimiento y datos antes del corte a producción.

    * Ejecutar pruebas con las **herramientas de Fiskil**
    * Cubrir **todos los endpoints** con escenarios distintos
    * Verificar **manejo de errores** y casos límite
    * Comprobar **rendimiento bajo carga**

    <Callout type="info">
      Guía detallada: [Visión general de pruebas](/es/data-holder/guides/testing).
    </Callout>
  </Step>
</Steps>

***

Recursos y próximos pasos [#recursos-y-próximos-pasos]

<Cards>
  <Card title="Guía de inicio rápido" href="/es/data-holder/guides/get-started/quickstart">
    Tutorial paso a paso para su primera integración con Fiskil.
  </Card>

  <Card title="Seguridad JWT" href="/es/data-holder/guides/build/jwt-security">
    Detalle de validación de tokens y configuración JWKS.
  </Card>

  <Card title="Herramientas de prueba" href="/es/data-holder/guides/testing">
    Recursos para probar su integración.
  </Card>
</Cards>

***

¿Necesita ayuda? [#necesita-ayuda]

<Callout type="info">
  Fiskil ofrece soporte durante toda la integración. Contacte a su equipo de cuenta o use la [Consola de Fiskil](https://console.fiskil.com) para asistencia técnica.
</Callout>


---

# Consentimientos (/es/data-holder/guides/build/consents)

Gestione los consentimientos de usuarios y permisos de acceso a datos.



Fiskil gestiona por usted todo el flujo de consentimiento, incluidas las pantallas de autorización y, de forma opcional, un panel de gestión del consentimiento para los usuarios. De este modo, usted puede centrarse en su producto mientras Fiskil ofrece una experiencia de consentimiento segura, intuitiva y conforme a la normativa.

Con Fiskil, no necesita diseñar ni implementar sus propias pantallas de consentimiento. En su lugar, puede integrar el flujo de consentimiento alojado mediante OAuth 2.0 y OpenID Connect (OIDC). A partir de ahí, Fiskil:

* Muestra pantallas de autorización claras y conformes
* Captura el consentimiento del usuario (alcances, duración, cuentas)
* Emite y valida tokens con los alcances correctos
* Proporciona APIs y vistas en la consola para la gestión de metadatos de consentimiento.
* Ofrece un panel opcional para el usuario final, donde puede revisar o revocar los consentimientos otorgados.

***

Ciclo de Vida del Consentimiento [#ciclo-de-vida-del-consentimiento]

En Fiskil, los consentimientos se administran como elementos centrales del sistema. Su ciclo de vida comprende:

* **Creación**: Un usuario otorga consentimiento durante el flujo de autorización. Se capturan los alcances solicitados, propósito y duración.
* **Activación**: Se emiten tokens con los alcances otorgados.
* **Revisión**: Los metadatos del consentimiento, historial y actividad de API asociada pueden revisarse en la Consola o a través de APIs.
* **Actualización**: Si los alcances o la duración cambian, el registro de consentimiento se actualiza y los nuevos tokens reflejan el cambio.
* **Revocación/Expiración**: Los usuarios pueden retirar el consentimiento en cualquier momento a través del dashboard, o los consentimientos pueden expirar automáticamente. Los tokens se invalidan inmediatamente.

***

Lo que Fiskil Proporciona [#lo-que-fiskil-proporciona]

* **Pantallas de consentimiento gestionadas por Fiskil**
* **Panel de gestión de consentimientos (opcional)**: Interfaz provista por Fiskil donde el usuario puede visualizar y revocar los consentimientos vigentes.
* **Consola y APIs**: Para que sus equipos inspeccionen metadatos de consentimiento, historial y llamadas API asociadas.
* **Cumplimiento integrado**: Los flujos de consentimiento siguen estándares globales de intercambio de datos (por ejemplo, CDR, FDX).

***

Integrándose con el Flujo de Consentimiento [#integrándose-con-el-flujo-de-consentimiento]

1. Su aplicación inicia OAuth2/OIDC con Fiskil.
2. El usuario es redirigido a la pantalla de consentimiento provista por Fiskil, personalizada con su logotipo y dominio.
3. El usuario revisa los conjuntos de datos solicitados, propósitos y duración.
4. El usuario aprueba el consentimiento; Fiskil lo registra y emite tokens con los alcances correctos.
5. Su aplicación recibe los tokens y los usa para llamar a su Resource Server.
6. Los metadatos del consentimiento son visibles en la Consola y accesibles a través de APIs.

***

Marca y Configuración [#marca-y-configuración]

Puede configurar la experiencia de consentimiento sin construirla usted mismo:

* [**Marca**](/es/data-holder/guides/configure/branding): Logo, nombre, colores
* [**Dominio personalizado**](/es/data-holder/guides/configure/custom-domains): por ejemplo, `consent.yourcompany.com`

***

Principios de Cumplimiento y UX [#principios-de-cumplimiento-y-ux]

Fiskil implementa las mejores prácticas en cada flujo de consentimiento para que no necesite construirlas usted mismo:

* **Claridad**: Mostrar quién solicita acceso, qué datos se compartirán y por cuánto tiempo.
* **Privilegio mínimo**: Los terceros solicitan acceso solo a los datos que necesitan especificando alcances.
* **Revocabilidad**: Opciones claras de retiro durante y después del consentimiento.
* **Confianza**: Alojado en su dominio de marca, evitando redirecciones innecesarias a terceros.

***

Relacionado [#relacionado]

* [Seguridad JWT](/es/data-holder/guides/build/jwt-security)
* [Pruebas con Fiskil](/es/data-holder/guides/testing)
* [Seguridad y Cumplimiento](/es/data-holder/guides/security/sso)


---

# Autenticación y autorización (/es/data-holder/guides/build/end-user-authentication)

Cómo se autentican sus usuarios y autorizan el intercambio de datos.



El flujo de consentimiento tiene dos partes: autenticación y autorización. A veces se denominan AuthN y AuthZ.

**Autenticación** es el proceso mediante el cual un usuario se identifica.
**Autorización** es el proceso mediante el cual un usuario determina qué datos se pueden compartir y durante cuánto tiempo.

Usted implementa APIs para que Fiskil autentique a sus usuarios y autorice el intercambio de datos.

Autenticación [#autenticación]

POST /auth/v1/customer/search [#post-authv1customersearch]

[Referencia](/es/data-holder/api-reference/cdr/auth-customer-search)

Fiskil incluye un sistema de autenticación integrado en el que los usuarios finales deben introducir un código de un solo uso (OTP) enviado a su correo electrónico o teléfono (vía SMS) para autenticarse. Para habilitar este proceso, su Resource Server debe implementar un endpoint de Customer Search.

Se usa para identificar al cliente asociado a la sesión autenticada.

**Propósito:**
Buscar un usuario a partir de la dirección de correo electrónico proporcionada durante la autenticación.

**Respuesta de ejemplo:**

```json
{
  "data": [
    {
      "id": "customerid",
      "name": "givenName familyName",
      "phoneNumber": "+6141234567890"
    }
  ]
}
```

El campo `phoneNumber` es opcional y solo se requiere para OTP por SMS.

GET /auth/v1/customer/{customerId} [#get-authv1customercustomerid]

[Referencia](/es/data-holder/api-reference/cdr/auth-customer-details)

Una vez autenticado el cliente, también necesitamos información básica sobre él para completar un [ID token](https://www.oauth.com/oauth2-servers/openid-connect/id-tokens/). Esto se obtiene mediante el endpoint de Customer Details.

Se usa para obtener los datos de identidad del cliente necesarios para emitir ID Tokens de OpenID Connect.

**Respuesta de ejemplo:**

```json
{
  "id": "customerid",
  "email": "hello@example.com",
  "emailVerified": true,
  "familyName": "Sherman",
  "givenName": "Peter",
  "name": "Peter Sherman",
  "phoneNumber": "+15551234567",
  "phoneNumberVerified": true,
  "updatedAt": "2025-07-01T00:00:00Z",
  "address": {
    "streetAddress": "42 Wallaby Way",
    "locality": "Sydney",
    "region": "NSW",
    "postalCode": "2000",
    "country": "AUS"
  }
}
```

<Callout type="info">
  Si aporta su propio proveedor de identidad (IdP), no necesita implementar los endpoints de Customer Search ni de Customer Details. Su IdP se encargará de la autenticación. Consulte [Proveedores de identidad externos](/es/data-holder/guides/configure/external-idp).
</Callout>

Autorización [#autorización]

Una vez autenticado, el usuario final debe definir los términos del intercambio de datos:

1. **Cuentas**: desde qué cuentas se compartirán los datos
2. **Scope**: qué conjuntos de datos de las cuentas elegidas se compartirán
3. **Duración**: durante cuánto tiempo se compartirán los datos

El endpoint de **Account List** se usa para facilitar la selección de cuentas. El scope y la duración los determina el cliente al realizar la solicitud de autorización.

GET /auth/v1/customer/{customerId}/accounts [#get-authv1customercustomeridaccounts]

[Referencia](/es/data-holder/api-reference/cdr/auth-customer-accounts)

Se usa para listar las cuentas disponibles para el cliente durante el consentimiento.

**Respuesta de ejemplo:**

```json
{
  "accounts": [
    {
      "id": "acc_001",
      "name": "Jane's Savings",
      "type": "savings",
      "displayName": "Account A"
    },
    {
      "id": "acc_002",
      "name": "Joint Account",
      "type": "transaction",
      "displayName": "Account B"
    }
  ]
}
```


---

# Seguridad JWT (/es/data-holder/guides/build/jwt-security)

Autenticación basada en JWT entre su Data Provider y Resource Server usando JWKS y tokens de corta duración.



La plataforma Fiskil Data Provider envía solicitudes a su servidor de recursos (Resource Server) para proporcionar los datos de sus usuarios a clientes autorizados. Para impedir que partes no autorizadas accedan a dichos datos, es imprescindible autenticar todas las solicitudes procedentes de Fiskil. Para ello, Fiskil Data Provider utiliza tokens JWT firmados, que pueden verificarse para confirmar que Fiskil es quien solicita los datos.

Flujo de autenticación del backend [#flujo-de-autenticación-del-backend]

El diagrama siguiente ilustra cómo funciona la autenticación entre el Data Provider de Fiskil y su Resource Server:

<Mermaid
  chart="sequenceDiagram
    participant DR as Receptor de Datos
    participant DP as Data Provider Fiskil
    participant RS as Su Resource Server
    participant JWKS as Endpoint JWKS

    DR->>DP: Solicitar datos con consentimiento
    DP->>DP: Generar token JWT
    Note over DP: Firma el JWT con clave privada<br/>Incluye claims aud, iss, sub

    DP->>RS: Solicitud API con JWT en el header Authorization
    RS->>JWKS: Obtener claves públicas (si no están en caché)
    JWKS-->>RS: Devolver JWKS con claves públicas

    RS->>RS: Validar firma del JWT
    RS->>RS: Validar claims (exp, aud, iss, sub, jti)

    alt Validación JWT exitosa
        RS-->>DP: Devolver datos solicitados
        DP-->>DR: Reenviar datos al receptor
    else Validación JWT fallida
        RS-->>DP: Devolver 401 Unauthorized
        DP-->>DR: Devolver respuesta de error
    end"
/>

JWT [#jwt]

El Data Provider de Fiskil utiliza [JSON Web Tokens (JWTs)](https://datatracker.ietf.org/doc/html/rfc7519) para autenticarse con su Resource Server. Los JWTs son adecuados para plataformas de datos abiertos porque permiten control de acceso granular y tiempos de vida cortos. Las solicitudes a su API incluyen un JWT en el header `Authorization` con el esquema Bearer.

Cada JWT está firmado por el Data Provider. Las claves públicas se exponen mediante un endpoint JWKS (compartido durante la incorporación). Los tokens incluyen un `kid` en el [header JOSE](https://www.rfc-editor.org/rfc/rfc7515.html#section-4.1.4) para que su servidor seleccione el JWK correcto.

La URL JWKS de su ambiente está disponible en la Consola en **Configuración → Dominios**.

Validar el JWT [#validar-el-jwt]

Una vez que tenga la clave pública, debe validar el JWT. Al validarlo, asegúrese de que:

* La firma sea válida.
* El token no haya expirado (revise el claim `exp`).
* Los claims `sub` e `iss` coincidan con el subdominio de su Data Provider (proporcionado durante la incorporación).
* El `aud` sea el URI del recurso solicitado en la API de Datos.
* El `jti` no se haya usado antes.

Ejemplo de implementación en Node.js [#ejemplo-de-implementación-en-nodejs]

Ejemplo completo en Node.js para validar JWTs del Data Provider de Fiskil:

```javascript
const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

// Configure el cliente JWKS (reemplace con su URL JWKS real)
const client = jwksClient({
  jwksUri: 'https://cdr.your-domain.com/.well-known/jwks.json',
  cache: true,
  cacheMaxAge: 3600000, // 1 hora
  rateLimit: true,
  jwksRequestsPerMinute: 5
});

// Almacene JTIs usados para prevenir ataques de replay
const usedJtis = new Set();

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    if (err) {
      return callback(err);
    }
    const signingKey = key.getPublicKey();
    callback(null, signingKey);
  });
}

async function validateFiskilJWT(token, requestUrl, expectedIssuer) {
  try {
    // Verificar y decodificar el JWT
    const decoded = jwt.verify(token, getKey, {
      algorithms: ['PS256', 'RS256'],
      issuer: expectedIssuer,
      audience: requestUrl,
      clockTolerance: 30 // Tolerancia de 30 s por desfase de reloj
    });

    // Validaciones adicionales
    const now = Math.floor(Date.now() / 1000);

    // Comprobar que el token no haya expirado
    if (decoded.exp <= now) {
      throw new Error('Token has expired');
    }

    // Comprobar que el subject coincida con el issuer
    if (decoded.sub !== expectedIssuer) {
      throw new Error('Subject claim does not match expected issuer');
    }

    // Comprobar replay del JTI
    if (usedJtis.has(decoded.jti)) {
      throw new Error('Token has already been used (replay attack)');
    }

    // Guardar el JTI para prevenir replay
    usedJtis.add(decoded.jti);

    // Limpie JTIs antiguos de forma periódica (según sus necesidades)
    // En producción, considere Redis u otro almacenamiento distribuido

    return {
      valid: true,
      claims: decoded
    };

  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

// Ejemplo de middleware de Express.js
function authenticateJWT(req, res, next) {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing or invalid Authorization header' });
  }

  const token = authHeader.substring(7); // Quitar el prefijo 'Bearer '
  const requestUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
  const expectedIssuer = 'https://cdr.your-domain.com'; // Reemplace con su dominio

  validateFiskilJWT(token, requestUrl, expectedIssuer)
    .then(result => {
      if (result.valid) {
        req.jwt = result.claims;
        next();
      } else {
        console.error('JWT validation failed:', result.error);
        res.status(401).json({ error: 'Invalid token' });
      }
    })
    .catch(error => {
      console.error('JWT validation error:', error);
      res.status(401).json({ error: 'Authentication failed' });
    });
}

// Uso en su ruta de Express
app.get('/v1/energy/customer/:customerId/accounts', authenticateJWT, (req, res) => {
  // Acceda a los claims validados mediante req.jwt
  console.log('Authenticated request from:', req.jwt.iss);
  console.log('Request ID:', req.jwt.jti);

  // Su lógica de API aquí
  res.json({ accounts: [] });
});
```

<Callout type="warning">
  Este ejemplo almacena los JTIs usados en memoria. En producción, use un caché distribuido como Redis para prevenir ataques de replay entre varias instancias del servidor.
</Callout>

<Callout type="idea">
  Considere implementar limpieza de JTIs para eliminar entradas expiradas y evitar fugas de memoria. Puede usar el claim `exp` para decidir cuándo limpiar cada JTI.
</Callout>

Ejemplo: solicitud autenticada [#ejemplo-solicitud-autenticada]

El ejemplo siguiente muestra un JWT usado para autenticar una solicitud a un proveedor de utilidades hipotético, **Acme Company**.

```http
GET /v1/energy/customer/bob/accounts HTTP/2
Host: data-api.acme-company.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVjZDdjMjEyLWM0YmQtNGRhNi04ZjhkLTgyNjUxODdiNDIwMCJ9.eyJpc3MiOiJodHRwczovL2Nkci5hY21lLWVuZXJneS5jb20iLCJzdWIiOiJodHRwczovL2Nkci5hY21lLWVuZXJneS5jb20iLCJhdWQiOiJodHRwczovL2RhdGEtYXBpLmFjbWU... (truncado)
```

<Callout type="info">
  Por seguridad y legibilidad, evite registrar tokens completos. Registre solo metadatos mínimos (por ejemplo, el `jti`).
</Callout>

JWT decodificado [#jwt-decodificado]

Header [#header]

```json
{
  "alg": "PS256",
  "typ": "JWT",
  "kid": "ecd7c212-c4bd-4da6-8f8d-8265187b4200"
}
```

Claims [#claims]

```json
{
  "iss": "https://cdr.acme-company.com",
  "sub": "https://cdr.acme-company.com",
  "aud": "https://data-api.acme-company.com/v1/energy/customer/bob/accounts",
  "iat": 1691939022,
  "exp": 1692939022,
  "jti": "2e7da1da-e410-48ec-827f-e17658dd87b2"
}
```

JWT es una especificación consolidada para compartir claims protegidos criptográficamente. Use una biblioteca de grado productivo para obtener JWKS y verificar JWTs en su lenguaje. Para más información, consulte las referencias siguientes.

<Cards>
  <Card title="JWT.IO — Introducción a JSON Web Tokens" href="https://jwt.io/introduction" icon={<DatabaseRestore />} />

  <Card title="JWT.IO — Bibliotecas de JSON Web Tokens" href="https://jwt.io/libraries" icon={<Building />} />
</Cards>

Firewall [#firewall]

Aunque el JWT basta para autenticar al Data Provider con su API, recomendamos añadir una lista de IPs permitidas en el firewall para reforzar la protección de sus datos.

* Fiskil proporciona direcciones IP para allow-listing durante la incorporación.
* Las direcciones IP también están disponibles en la Consola en [**Configuración → Resource Server**](https://console.fiskil.com/data-holder/settings/resource-server).

Notas finales [#notas-finales]

La seguridad es un tema complejo y suele implicar un equilibrio entre rigurosidad y facilidad de uso. Si estos mecanismos no cumplen sus expectativas, contacte al equipo de Fiskil para evaluar esquemas alternativos que faciliten la incorporación y protejan la información sensible de sus clientes.


---

# Resource Server (/es/data-holder/guides/build/resource-server)

Responsabilidades, contratos y guía de implementación para un Resource Server conforme.



El Resource Server es la API de datos de su aplicación: se encarga de exponer los datos del cliente después de que este haya otorgado su consentimiento.

Fiskil gestiona la autorización, la emisión de tokens y la orquestación del consentimiento. Durante el proceso de consentimiento y una vez que el usuario aprueba el acceso, Fiskil llama a su Resource Server con un JWT. Su tarea es validar ese token y devolver los datos correspondientes.

***

Cómo funciona [#cómo-funciona]

El diagrama siguiente ilustra el flujo completo de integración del Resource Server:

<Mermaid
  chart="sequenceDiagram
    participant User as Usuario final
    participant DR as Receptor de Datos
    participant DP as Data Provider de Fiskil
    participant RS as Su Resource Server
    participant DB as Su base de datos

    User->>DR: Inicia solicitud de datos
    DR->>DP: Solicita autorización de consentimiento
    DP->>User: Presenta pantalla de consentimiento
    User->>DP: Aprueba el intercambio de datos

    Note over DP: Genera token JWT<br/>según los permisos aprobados

    DP->>RS: Solicitud API con JWT
    RS->>RS: Valida firma y claims del JWT
    RS->>RS: Verifica el token frente a los requisitos del endpoint

    alt Token válido y con permisos suficientes
        RS->>DB: Consulta datos del cliente
        DB-->>RS: Devuelve los datos solicitados
        RS-->>DP: Devuelve datos (JSON)
        DP-->>DR: Reenvía datos al receptor
        DR-->>User: Presenta los datos en la aplicación
    else Token inválido
        RS-->>DP: Devuelve error 401/403
        DP-->>DR: Devuelve respuesta de error
        DR-->>User: Muestra mensaje de error
    end"
/>

Ejemplo de endpoint de datos [#ejemplo-de-endpoint-de-datos]

Se requiere al menos un endpoint que exponga datos reales para probar e ir a go-live. La API debe comenzar con `/customer/{customerId}` para que obtengamos datos del cliente que otorgó el consentimiento.

GET /customer/{customerId}/accounts/{id}/balances [#get-customercustomeridaccountsidbalances]

Devuelve el saldo de la cuenta.

**Respuesta de ejemplo:**

```json
{
  "account_id": "acc_001",
  "available": 1200.50,
  "current": 1250.75,
  "currency": "AUD"
}
```

Puede devolver datos simulados (mock) durante la fase inicial de pruebas.

***

Próximos pasos [#próximos-pasos]

* [Revisar Fiskil Firewall y límites de capacidad](/es/data-holder/guides/security/firewall)
* [Implementar APIs de autenticación y autorización](/es/data-holder/guides/build/end-user-authentication)
* [Configurar la validación JWT](/es/data-holder/guides/build/jwt-security)
* [Registrar su Resource Server en la Consola](/es/data-holder/guides/get-started/instances)
* [Revisar la checklist de go-live](/es/data-holder/guides/go-live)


---

# Marca (/es/data-holder/guides/configure/branding)



Fiskil administra en su nombre las **pantallas de autorización de consentimientos y el panel opcional de gestión de consentimientos**. Es posible personalizar la identidad visual para ofrecer a los clientes una experiencia confiable y alineada con la imagen corporativa de su organización.

La marca se configura por ambiente en la [**Consola → Configuración → Marca**](https://console.fiskil.com/data-holder/settings/domains).

***

Qué Puede Personalizar [#qué-puede-personalizar]

Puede editar los siguientes elementos para cada ambiente:

* **Fuente**: elija tipografía que coincida con su marca.
* **Logos**: suba el logo de su organización para usar en flujos de consentimiento y dashboards.
* **Colores de Marca**: aplique colores primarios/secundarios para botones, resaltados y acentos de UI.
* **Información de Identidad Empresarial**: muestre el nombre de su organización e identificadores relacionados.
* **Información de Soporte**: proporcione detalles de contacto de soporte al cliente (correo, teléfono, enlace).
* **Enlaces de Políticas**: enlace a su política de privacidad, términos de servicio o centro de ayuda.
* …y más.

***

Pantallas de Consentimiento [#pantallas-de-consentimiento]

Todos los usuarios completan su consentimiento a través del **flujo de consentimiento alojado por Fiskil**.
La marca asegura que estas pantallas se sientan consistentes con la experiencia de su producto.

El flujo de consentimiento siempre muestra:

* El **Receptor de Datos** que solicita acceso
* Los **alcances y conjuntos de datos** solicitados
* La **duración** del acceso
* Su **logo, fuente y colores de marca** configurados
* Cualquier **enlace de soporte o políticas** que proporcione

***

Dashboard del Consumidor (Opcional) [#dashboard-del-consumidor-opcional]

Si está habilitado, Fiskil proporciona un **dashboard de usuario final** donde los clientes pueden:

* Ver sus consentimientos activos
* Revocar consentimientos en cualquier momento

Su marca también aplica aquí:

* Logo y nombre de visualización
* Fuente y colores de marca
* Dominio personalizado

***

Mejores Prácticas [#mejores-prácticas]

* Distinga claramente su marca de **Staging** y **Producción** para reducir las posibilidades de usar el ambiente incorrecto.
* Use un **dominio personalizado** para ambientes de producción (por ejemplo, `consent.acme.com`).
* Proporcione **información de soporte** clara y accesible y **enlaces de políticas** para generar confianza.
* Use activos de alta resolución para logos e iconos para asegurar accesibilidad.

***

Relacionado [#relacionado]

* [Dominio Personalizado](/es/data-holder/guides/configure/custom-domains)
* [Consentimiento](/es/data-holder/guides/build/consents)
* [Ambientes](/es/data-holder/guides/get-started/instances)


---

# Dominios Personalizados (/es/data-holder/guides/configure/custom-domains)



Puede configurar un **dominio personalizado** para su ambiente de Data Provider para que los clientes interactúen con un dominio de marca familiar (por ejemplo, `consent.acme-corp.com`).

Este dominio se usará para:

* Pantallas de autorización de consentimiento
* Panel opcional de gestión de consentimientos para el usuario
* Endpoints de API seguros (HTTPS con soporte opcional de mTLS)
* Servicio de envío de correos electrónicos (OTP y notificaciones)

<Info>
  Siempre puede ver el dominio activo para su Data Provider en la [Consola → Configuración → Dominios](https://console.fiskil.com/data-holder/settings/domains).
</Info>

***

Agregando un Dominio Personalizado [#agregando-un-dominio-personalizado]

Configure dominios en la Consola bajo **Dominios Personalizados**.

<Steps>
  <Step>
    Haga clic en 

    **Agregar Dominio**
  </Step>

  <Step>
    Ingrese el subdominio deseado (por ejemplo, 

    `cdr.acme-corp.com.au`

    ). Debe ser un subdominio del dominio raíz de su organización.
  </Step>

  <Step>
    Haga clic en 

    **Siguiente**
  </Step>

  <Step>
    Cree los registros DNS requeridos como se muestra en la Consola
  </Step>

  <Step>
    Haga clic en 

    **Iniciar Verificación**
  </Step>
</Steps>

* Si los registros DNS se verifican exitosamente, Fiskil aprovisionará certificados TLS y actualizará su ambiente.
* La propagación puede tomar tiempo; siga el progreso en la Consola.
* Una vez que un dominio está configurado, no puede cambiarse sin asistencia. Si necesita reiniciar, [contacte a soporte](https://fiskil.atlassian.net/servicedesk/customer/portal/6/group/23/create/55?summary=Change+custom+domain).

Puede configurar **dominios personalizados separados** para staging y producción. Cambie entre entornos usando el menú desplegable en la parte superior derecha del menú de Dominios Personalizados.

***

Registros DNS Requeridos [#registros-dns-requeridos]

Al habilitar un dominio personalizado, se deben crear múltiples registros DNS:

1. Registros de Endpoint (CNAME) [#1-registros-de-endpoint-cname]

* Los registros CNAME mapean su dominio personalizado a los subdominios asignados por Fiskil.
* Requeridos para:
  * Endpoints de API HTTPS
  * Endpoints de API mTLS
  * UI de autorización de consentimiento
  * Dashboard de consentimiento

***

2. Registros CAA (Certificados TLS) [#2-registros-caa-certificados-tls]

* Se requieren dos registros CAA para que Fiskil pueda usar Google y Let's Encrypt para aprovisionar certificados TLS.
* Asegura que los navegadores confíen en su dominio personalizado.

***

3. Registros de Correo (Autenticación) [#3-registros-de-correo-autenticación]

Fiskil envía correos desde el dominio de su Data Provider (por ejemplo, para OTPs y notificaciones).
Para asegurar la entregabilidad, configure:

* **DKIM y SPF**:
  * Registros `CNAME` para `em***.<custom-domain>`
  * `s1._domainkey.<custom-domain>`
  * `s2._domainkey.<custom-domain>`

* **DMARC**:
  * Registro `TXT` para `_dmarc.<custom-domain>`
  * Define una política DMARC para rechazar mensajes no autenticados

En conjunto, estos registros permiten a los servidores de correo validar la autenticidad de los mensajes enviados desde su dominio, mitigando riesgos de suplantación de identidad y optimizando la tasa de entrega.

***

Mejores Prácticas [#mejores-prácticas]

* Use subdominios separados para **staging** y **producción** (por ejemplo, `consent.staging.acme-corp.com`, `consent.acme-corp.com`).
* Se recomienda configurar los registros DNS con antelación, dado que el proceso de verificación depende de la propagación y puede demorar varias horas.
* Aplique políticas DMARC estrictas (`p=reject`) para dominios de producción.

***

Relacionado [#relacionado]

* [Dominios Personalizados](/es/data-holder/guides/configure/custom-domains)
* [Marca y Pantalla de Consentimiento](/es/data-holder/guides/configure/branding)
* [Ambientes](/es/data-holder/guides/get-started/instances)


---

# Proveedores de identidad externos (/es/data-holder/guides/configure/external-idp)

Cómo integrar su propio proveedor de identidad en su ambiente Fiskil.



Si ya cuenta con un proveedor de identidad (IdP) y este soporta OpenID Connect (OIDC), puede integrarlo con Fiskil para aplicar los mismos estándares robustos de autenticación que usa en otras aplicaciones.

<Callout type="info">
  Configurar un proveedor de identidad externo es **opcional**. Fiskil puede usar una experiencia de autenticación [integrada](/es/data-holder/guides/build/end-user-authentication#autenticación) facilitada por su Resource Server.
</Callout>

Al integrar un IdP con Fiskil, el paso de [Customer Search](/es/data-holder/guides/build/end-user-authentication#post-authv1customersearch) lo gestiona su IdP. No necesita implementar un endpoint de Customer Search en su Resource Server. Así ahorra tiempo y mantiene una experiencia de autenticación consistente para sus usuarios.

<Callout type="warning">
  Si opera en un ecosistema de datos abiertos regulado, confirme que su IdP puede cumplir los estándares de autenticación de ese ecosistema.
</Callout>

Conectar su IdP a Fiskil [#conectar-su-idp-a-fiskil]

Configurar su IdP con Fiskil implica agregar a Fiskil como cliente OIDC en su IdP.

Agregar Fiskil como cliente en su IdP [#agregar-fiskil-como-cliente-en-su-idp]

1. Configure las URL de redirección de Fiskil en `https://<su-dominio-data-provider>/idp/auth/login` y `https://<su-dominio-data-provider>/idp/auth/consent`
   * Puede obtener el dominio de su Data Provider en el menú [Dominios](https://console.fiskil.com/data-holder/settings/domains) de la Consola de Fiskil
   * Conviene esperar a tener un dominio personalizado antes de agregar el IdP, para no repetir el proceso si el dominio del Data Provider cambia
2. Guarde el client ID y el client secret creados para Fiskil
3. Anote la URL base del servicio OpenID Connect de su IdP

<Callout type="info">
  Al agregar Fiskil como cliente en su IdP, consulte la documentación del servicio OpenID Connect de su proveedor.
</Callout>

Agregar su IdP en la Consola de Fiskil [#agregar-su-idp-en-la-consola-de-fiskil]

1. Abra el menú de configuración del Identity Provider en la [Consola de Fiskil](https://console.fiskil.com/data-holder/settings/external-idp)
2. Haga clic en **Edit**
3. Indique el Client ID, Client Secret y Base URL del paso 1
4. Haga clic en **Save**

<Callout type="info">
  Fiskil depende del documento de OpenID Discovery que sirve su IdP. Si recibe un error sobre el “OpenID Connect Discovery endpoint”, confirme que existe un endpoint `/.well-known/openid-configuration` en la URL base que proporcionó.
</Callout>

Probar [#probar]

Ejecute un flujo de autorización con nuestras herramientas de pruebas. Consulte la documentación de [Pruebas](/es/data-holder/guides/testing) según su tipo de integración para más detalles sobre cómo completar una autorización de prueba.

Limitaciones [#limitaciones]

* Fiskil solo funciona con OpenID Connect para identidad federada. Su IdP debe soportarlo.
* El ID Token que devuelve su IdP debe incluir un claim `sub` **único** y **estable** para el usuario autenticado. No debe cambiar entre consentimientos.
* El claim `sub` del ID token debe servir como ID para buscar los datos del usuario autenticado. Se usará como parámetro de ruta `{customerId}` en las solicitudes a su Resource Server.
* Si su IdP está detrás de un firewall, debe permitir el acceso desde las direcciones IP del Data Provider de Fiskil. Puede obtenerlas en la [configuración del Resource Server](https://console.fiskil.com/data-holder/settings/resource-server) del Data Provider.

Si tiene dudas sobre si podemos soportar su IdP, contáctenos y lo evaluamos con usted.


---

# Visión General (/es/data-holder/guides/configure)



Después de haber construido y probado su Resource Server, el siguiente paso es configurar sus **ambientes** para estar listos para producción.

La configuración se gestiona por ambiente en la **Consola de Fiskil**. Cada ambiente (staging o producción) tiene su propia configuración para dominios, marca, seguridad y perfiles de cumplimiento opcionales.

***

Qué Puede Configurar [#qué-puede-configurar]

* **Dominios Personalizados**
  Use su propio nombre DNS (por ejemplo, `consent.yourcompany.com`) para flujos de consentimiento alojados.
  Ver: [Dominio Personalizado](/es/data-holder/guides/configure/custom-domains)

* **Marca**
  Controle cómo se presentan las pantallas de consentimiento y dashboards a sus clientes con su logo y nombre de visualización.
  Ver: [Marca y Pantalla de Consentimiento](/es/data-holder/guides/configure/branding)

* **Configuración del Resource Server**
  Defina la URL base, validación JWKS, mTLS opcional y listas de IPs permitidas del firewall.
  Ver: [Configuración del Resource Server](/es/data-holder/guides/configure/resource-server-settings)

* **Perfiles de Cumplimiento** (opcional)
  Aplique alcances, headers y comportamientos preconfigurados alineados con estándares como CDR o FDX.

***

Dónde Ocurre la Configuración [#dónde-ocurre-la-configuración]

Toda la configuración está disponible en la **Consola → Configuración de Ambiente**.

Cada ambiente tiene:

* Sus propios **dominios** (staging vs producción)
* Sus propias **claves y secretos**
* Sus propios **registros y métricas**

***

Mejores Prácticas [#mejores-prácticas]

* **Separar entornos**: Mantenga los ambientes de staging y producción aislados con su propio DNS, claves y secretos.
* **Migrar de forma segura**: Pruebe los cambios de configuración en staging antes de aplicarlos a producción.
* **Bloquear producción**: Use listas de IPs permitidas estrictas, validación de DNS y control de cambios para tráfico en vivo.

***

Relacionado [#relacionado]

* [Ambientes](/es/data-holder/guides/get-started/instances)
* [Dominio Personalizado](/es/data-holder/guides/configure/custom-domains)
* [Marca y Pantalla de Consentimiento](/es/data-holder/guides/configure/branding)
* [Configuración del Resource Server](/es/data-holder/guides/configure/resource-server-settings)


---

# Incorporación de Clientes (/es/data-holder/guides/configure/onboarding-clients)

Invita a terceros a integrarse con tu Data Provider



Cuando estés listo para incorporar desarrolladores externos, tendrás que registrarlos como Clientes en tu Data Provider. La forma de hacerlo depende
de la industria y la jurisdicción en la que operes.

* **CDR**: La incorporación de clientes se realiza mediante el [Protocolo de Registro Dinámico de Clientes de OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc7591). Cualquier
  receptor de datos acreditado puede registrarse directamente en tu instancia del Data Provider a través de la API.
* **FDX**: La incorporación de clientes FDX se gestiona a través de Plaid. Al añadir Plaid como cliente obtienes acceso a su amplia red de socios.
* **Otros**: Si ejecutas un Data Provider FAPI 2.0 simple en otra jurisdicción, debes incorporar los clientes manualmente en la Consola de Fiskil

Incorporación de clientes en la Consola de Fiskil [#incorporación-de-clientes-en-la-consola-de-fiskil]

Si operas un Data Provider FAPI 2.0 simple, tendrás que añadir los clientes manualmente en la [Consola de Fiskil](https://console.fiskil.com/data-holder/settings/client-registration).
Este proceso consta de dos pasos.

Registrar el cliente [#registrar-el-cliente]

Los Data Providers FAPI 2.0 usan `private_key_jwt` como [método de autenticación de cliente de OIDC](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.9). Este es uno de
los métodos aceptados por el estándar FAPI 2.0. Los clientes deben registrar previamente una clave pública que pueda utilizarse para verificar las aserciones JWT que emiten como parte de la autenticación de cliente. Sigue
los pasos que se indican a continuación desde el menú [Clientes registrados](https://console.fiskil.com/data-holder/settings/client-registration).

1. Haz clic en "Agregar nuevo cliente"
2. Completa el formulario
   * **Client Name**: Un nombre legible para el cliente. Se mostrará a tus usuarios durante el flujo de consentimiento
   * **JWKS URI** El JWKS URI del cliente. Debe ser HTTPS. Esta URL apunta a la clave pública que el cliente usa para la autenticación de cliente con Private Key JWT y para los objetos de solicitud de autorización enviados (pushed authorization request objects)
   * **Brand Image** Un logo para el cliente. Se mostrará a los usuarios finales durante el flujo de consentimiento.
3. Confirma haciendo clic en "Add Client"

Emitir certificados de cliente [#emitir-certificados-de-cliente]

Los Data Providers FAPI 2.0 usan mTLS como medida adicional de seguridad en el transporte y como mecanismo para admitir tokens de acceso vinculados al emisor (sender-constrained)
tal como se define en el [RFC 8705](https://www.rfc-editor.org/info/rfc8705/). Los certificados mTLS son emitidos por la autoridad certificadora privada FAPI 2.0 de Fiskil.
Los pasos para obtener un certificado de cliente mTLS para un nuevo cliente son:

1. Pide a tu cliente que te envíe una Solicitud de Firma de Certificado (CSR) en formato DER codificado en PEM
2. En el menú [Clientes registrados](https://console.fiskil.com/data-holder/settings/client-registration), busca el cliente en la tabla
3. Haz clic en el menú **Acciones** de la fila del cliente y selecciona "Gestionar certificados"
4. Haz clic en **Crear certificado** en el diálogo que se abre
5. Pega la CSR en el área de texto y haz clic en **Crear**
6. Copia el **Certificado** y la **Cadena de certificados** del diálogo de resultado y envía ambos a tu cliente. Ten en cuenta que solo necesitan presentar el certificado de hoja (leaf)
   para establecer una conexión con el endpoint mTLS de tu Data Provider

<Note>
  Si tu cliente necesita ayuda para generar una CSR, puede usar el siguiente fragmento para crear una CSR y una clave privada de una sola vez:

  ```bash
  openssl req -new -newkey rsa:2048 -keyout client.key -sha256 -subj "/CN=My New Client" -out client.csr -nodes
  ```

  Pídele que te envíe `client.csr`. Asegúrate de que mantenga el archivo `client.key` en privado y lo guarde en un lugar seguro, ya que es la clave privada que debe usar con el certificado emitido
</Note>


---

# Configuración del Resource Server (/es/data-holder/guides/configure/resource-server-settings)



Cada ambiente del Data Provider debe estar vinculado a un **Resource Server**: su API que expone datos de clientes y productos.

La configuración se gestiona en la [**Consola → Configuración → Resource Server**](https://console.fiskil.com/data-holder/settings/resource-server).
La configuración se aplica por ambiente (staging, producción).

***

Qué Configura [#qué-configura]

* **URL Base**
  La URL HTTPS pública de su Resource Server. Debe ser accesible desde Fiskil.

* **URL JWKS**
  El endpoint JWKS usado para validar los JWTs de [Seguridad JWT](/es/data-holder/guides/build/jwt-security) de Fiskil.
  * Obtiene la clave pública de su ambiente desde esta URL

* **Listas de IPs Permitidas del Firewall (opcional)**
  Restrinja el tráfico entrante a solicitudes originadas desde las IPs de Fiskil visibles en el menú del Resource Server.

***

Mejores Prácticas [#mejores-prácticas]

* Siempre use **URLs de Resource Server distintas** para staging y producción.
* Use listas de IPs permitidas del firewall para entornos de producción.

***

Relacionado [#relacionado]

* [Ambientes](/es/data-holder/guides/get-started/instances)
* [Visión General de Construcción](/es/data-holder/guides/build/resource-server)
* [Seguridad JWT](/es/data-holder/guides/build/jwt-security)


---

# Ambientes (/es/data-holder/guides/get-started/instances)

Despliegue y gestione ambientes del Data Provider para sus entornos.



Un **ambiente** corresponde a un Data Provider desplegado de manera independiente, con configuración, DNS, claves criptográficas y registros operativos propios. Cada ambiente opera de forma totalmente aislada, manteniendo secretos, claves JWKS, registros de auditoría y logs de solicitudes segregados.

***

Staging vs Producción [#staging-vs-producción]

Cada ambiente está etiquetado como `staging` o `production`.

* **Staging**
  * Entorno flexible con herramientas de prueba
  * Soporta receptores simulados e iteración más fácil
  * Controles de cambio relajados

* **Producción**
  * Orientado al cliente y crítico para el cumplimiento
  * Control de cambios estricto y requisitos de auditoría
  * Postura de seguridad reforzada

***

Qué Configura Por Ambiente [#qué-configura-por-ambiente]

Cada ambiente puede configurarse de forma independiente:

* **Dominios**: DNS personalizado (ver [Dominio Personalizado](/es/data-holder/guides/configure/custom-domains))
* **Marca**: Logo, nombre de visualización e identidad de pantalla de consentimiento (ver [Marca](/es/data-holder/guides/configure/branding))
* **Configuración del Resource Server**: URL base, validación JWT (JWKS), mTLS opcional
* **Perfil de cumplimiento** (opcional): Alcances, headers y comportamientos preconfigurados para estándares como CDR o FDX

***

Ciclo de Vida Típico [#ciclo-de-vida-típico]

1. Sus ambientes son desplegados por Fiskil cuando se incorpora.
2. Integre su Resource Server con el ambiente de **staging** y valide usando herramientas de prueba.
3. Conecte su Resource Server finalizado al ambiente de **producción** con DNS bloqueado, secretos y alertas.
4. Promueva cambios de staging → producción usando lanzamientos versionados y programados.

<Callout type="info">
  Migre los cambios a través de Staging antes de Producción. Mantenga DNS, claves y secretos distintos para cada ambiente.
</Callout>


---

# Inicio rápido (/es/data-holder/guides/get-started/quickstart)

Lance su primera integración de Data Provider —desde el Resource Server hasta la validación de extremo a extremo— en menos de una hora.



Lance su primera integración de Data Provider —desde el Resource Server hasta la validación de extremo a extremo— en menos de una hora.

**Tiempo estimado**: 30–60 minutos

***

Antes de comenzar [#antes-de-comenzar]

Para seguir esta guía, necesitará:

* Acceso a la Consola de Fiskil con permisos de administrador de la organización
* Un dominio bajo su control (para DNS y configuración de marca)
* Un ingeniero para implementar o simular su Resource Server

***

Paso 1 — Aprovisionar sus entornos [#paso-1--aprovisionar-sus-entornos]

Una vez aprobado en la plataforma Fiskil Data Provider, le aprovisionaremos instancias separadas de Staging y Production.

Cada instancia está aislada e incluye:

* Claves específicas del entorno
* Registros y métricas separados
* Herramientas de pruebas y sandbox

Use Staging para todo el desarrollo e integración inicial.

***

Paso 2 — Implementar un Resource Server mínimo [#paso-2--implementar-un-resource-server-mínimo]

Su Resource Server es su API: Fiskil la llamará después de que un usuario otorgue su consentimiento.

Para su primera integración, deberá implementar los siguientes endpoints:

Endpoints requeridos [#endpoints-requeridos]

| Endpoint                                                      | Propósito                                                         | Referencia                                                         |
| ------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| `GET /auth/v1/customer/search`                                | Identificar al cliente durante el flujo de consentimiento         | [Enlace](/es/data-holder/api-reference/cdr/auth-customer-search)   |
| `GET /auth/v1/customer/{customerId}/accounts`                 | Listar las cuentas disponibles para compartir                     | [Enlace](/es/data-holder/api-reference/cdr/auth-customer-accounts) |
| `GET /auth/v1/customer/{customerId}`                          | Obtener información de identidad del cliente                      | [Enlace](/es/data-holder/api-reference/cdr/auth-customer-details)  |
| `GET /v1/customer/{customerId}/accounts/{accountId}/balances` | Ejemplo de endpoint de datos para exponer información del cliente |                                                                    |

Estos endpoints deben:

* Ser accesibles por el Data Provider de Fiskil a través de HTTPS
* Aceptar tokens Bearer y validarlos con el JWKS de Fiskil

<Callout type="info">
  Para las pruebas iniciales, estos endpoints pueden devolver datos estáticos o simulados (mock).
</Callout>

Ejemplo: endpoint de balances [#ejemplo-endpoint-de-balances]

```bash
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
  https://<su-resource-server>/v1/customer/{customerId}/accounts/{account_id}/balances
```

Ejemplo de respuesta:

```json
{
  "account_id": "acc_001",
  "available": 1200.50,
  "current": 1250.75,
  "currency": "AUD"
}
```

***

Paso 3 — Vincular su Resource Server [#paso-3--vincular-su-resource-server]

En la [Consola](https://console.fiskil.com/data-holder/settings/resource-server):

* Configure la URL base de su Resource Server en la instancia `staging`
* *(Opcional)* Configure una allowlist para restringir el tráfico entrante a las IPs de Fiskil
* Confirme que su API es accesible y está en buen estado

***

Paso 4 — Configurar marca y DNS [#paso-4--configurar-marca-y-dns]

[Personalice](https://console.fiskil.com/data-holder/branding) el flujo de consentimiento orientado al usuario con:

* Su logo y nombre para mostrar
* Un dominio personalizado, por ejemplo `consent.suempresa.com`

Para configurarlo, consulte: [Configuración de dominio personalizado](/es/data-holder/guides/configure/custom-domains)

***

Paso 5 — Ejecutar una prueba de extremo a extremo [#paso-5--ejecutar-una-prueba-de-extremo-a-extremo]

Use las herramientas de pruebas de Fiskil para validar el flujo completo de consentimiento.

Como parte de su onboarding, le invitaremos a nuestras herramientas de pruebas. Estas dependen del tipo de integración que esté construyendo: si opera bajo un estándar regulatorio o si es un proveedor de datos voluntario.

***

Paso 6 — Ir más allá [#paso-6--ir-más-allá]

Una vez validada su integración:

* Avanzar con la implementación en el ambiente de producción, haciendo una prueba de extremo a extremo
* Habilite registros y métricas. Consulte [Logs](/es/data-holder/guides/telemetry/logs) y [Metrics](/es/data-holder/guides/telemetry/metrics)

***

Paso 7 — Go-live [#paso-7--go-live]

Para lanzar en producción:

* Complete cualquier certificación o validación regulatoria requerida (si aplica)
* Registre e incorpore clientes terceros de confianza (p. ej., Plaid, aplicaciones de energía)
* Apunte las integraciones de producción a su instancia en vivo

***

Resumen de conceptos clave [#resumen-de-conceptos-clave]

**Instance**
Un entorno aislado con su propio dominio, claves, registros y configuración.

**Resource Server**
Su API: expone los datos del cliente y responde a Fiskil mediante contratos estándar.

**Scopes y Consent**
Sus clientes deben consentir el intercambio de datos. El alcance de ese consentimiento define qué datos pueden compartirse. Fiskil gestiona los Scopes y los Consents.

**Compliance Profile**
Una plantilla de comportamiento predefinida (headers, scopes, APIs) basada en estándares como CDR o FDX.


---

# Lista de Verificación para Producción (/es/data-holder/guides/go-live)

Guía completa para validar que su Data Provider está listo para producción, incluyendo requisitos de cumplimiento e incorporación de receptores de datos.



Ir a producción significa más que crear un ambiente de producción: incluye incorporar **Receptores de Datos** y, si aplica, cumplir obligaciones regulatorias.

Esta lista de verificación completa cubre **preparación técnica**, **preparación operacional** y **cumplimiento regulatorio** para asegurar un despliegue a producción sin problemas.

***

Entendiendo las Responsabilidades [#entendiendo-las-responsabilidades]

Antes de entrar en la lista de verificación, es importante entender qué maneja Fiskil versus sus responsabilidades.

<Tabs items={["Qué Maneja Fiskil", "Sus Responsabilidades"]}>
  <Tab value="Qué Maneja Fiskil">
    <ul className="list-disc pl-6 my-2 space-y-1">
      <li>
        Divulgación de datos segura y compatible con estándares
      </li>

      <li>
        Flujos de gestión de consentimiento y dashboard opcional del consumidor
      </li>

      <li>
        Servicios de autenticación y autorización (OIDC, alcances, tokens)
      </li>

      <li>
        <a href="/es/data-holder/guides/security/firewall">Fiskil Firewall</a>

        : limitación de receptores, mitigación DDoS y protección frente a IPs maliciosas
      </li>

      <li>
        Registro operacional, pistas de auditoría y retención
      </li>
    </ul>
  </Tab>

  <Tab value="Sus Responsabilidades">
    <ul className="list-disc pl-6 my-2 space-y-1">
      <li>
        Soporte al cliente, resolución de disputas y manejo de quejas
      </li>

      <li>
        Publicar una 

        <strong>Política de Compartición de Datos</strong>

         (o equivalente, si lo requiere su régimen)
      </li>

      <li>
        Prácticas internas de cumplimiento (gobernanza, gestión de riesgos, capacitación)
      </li>

      <li>
        Coordinarse con reguladores, integradores o registros donde aplique
      </li>
    </ul>
  </Tab>
</Tabs>

<Info>
  Vea nuestra [sección de Preguntas Frecuentes](/es/data-holder/guides/help/faq) para información detallada sobre responsabilidades de cumplimiento.
</Info>

***

Lista de Verificación Pre-Producción [#lista-de-verificación-pre-producción]

Complete estos pasos antes de incorporar Receptores de Datos para asegurar que su Data Provider está listo para producción.

<Steps>
  <Step title="Precondiciones Técnicas">
    Asegure que su Resource Server cumple todos los requisitos técnicos:

    * [ ] Resource Server implementado y probado en **staging**
    * [ ] Autenticación validada: firmas JWT verificadas, claims `aud`/`iss` aplicados
    * [ ] Modelo de errores y paginación consistentes con estándares de Fiskil
  </Step>

  <Step title="Configuración de Ambiente de Producción">
    Configure su entorno de producción:

    * [ ] Ambiente de producción creado en la Consola
    * [ ] Dominio personalizado configurado y DNS propagado
    * [ ] Branding y políticas revisados en la Consola
  </Step>

  <Step title="Pruebas de Extremo a Extremo">
    Valide que todos los sistemas funcionan correctamente juntos:

    * [ ] Flujos de consentimiento de extremo a extremo validados en **staging** (creación de consentimiento, emisión de token, llamadas de API)
    * [ ] Evidencia capturada (registros, capturas de pantalla) para propósitos de auditoría
    * [ ] Registros de Solicitudes revisados en la Consola; Log Drains configurados si usa SIEM externo
    * [ ] Métricas revisadas para latencia, tasas de error y throughput bajo carga de prueba
  </Step>

  <Step title="Preparación Operacional">
    Asegure que su equipo está preparado para soportar operaciones de producción:

    * [ ] Monitoreo y alertas configurados en Registros y Métricas (si reenvía a herramientas externas)
    * [ ] Equipos capacitados en acceso a Registros y Métricas en la Consola
    * [ ] Procedimientos establecidos para responder a solicitudes de soporte de Receptores de Datos
    * [ ] Procesos de escalación definidos para problemas internos o soporte de Fiskil
  </Step>

  <Step title="Validación de Cumplimiento y Regulatoria">
    Complete los pasos de cumplimiento requeridos para su mercado:

    * [ ] Pruebas de conformidad completadas para su perfil de cumplimiento (por ejemplo, CDR, FDX)
    * [ ] URIs de redirección registradas y verificadas para staging y producción
    * [ ] Aprobación o certificación regulatoria completada (si se requiere)

    <Warning>
      Si no va a producción con un perfil de cumplimiento pero requiere incorporación regulatoria, [contacte al equipo de Fiskil](https://fiskil.com/contact) para soporte con validación y requisitos de registro/integrador.
    </Warning>
  </Step>
</Steps>

***

Proceso de Ir a Producción [#proceso-de-ir-a-producción]

Una vez que haya completado la lista de verificación pre-producción, siga estos pasos para incorporar Receptores de Datos y monitorear su despliegue de producción.

<Steps>
  <Step title="Incorporar Receptores de Datos">
    Comience a integrar con receptores de confianza:

    * [ ] Agregue Receptores de Datos de confianza en la Consola (integraciones directas o apps aprobadas por registro)
    * [ ] Valide flujos de consentimiento e intercambio de datos con cada receptor
    * [ ] Comience con un número pequeño de receptores para monitorear comportamiento del sistema

    <Tip>
      Comience con **Receptores de Datos de confianza** con los que ha trabajado durante las pruebas para asegurar despliegues iniciales sin problemas.
    </Tip>
  </Step>

  <Step title="Monitorear Tráfico Inicial">
    Observe de cerca sus primeros intercambios de datos de producción:

    * [ ] Monitoree el primer tráfico de producción en Registros y Métricas para confirmar operación estable
    * [ ] Vigile cualquier patrón de error inesperado o problemas de rendimiento
    * [ ] Valide que todos los flujos de consentimiento funcionan como se espera en producción
    * [ ] Primer tráfico de producción procesado exitosamente con métricas estables
  </Step>

  <Step title="Escalar Incorporación de Receptores">
    Expanda gradualmente su red de receptores:

    * [ ] Continúe incorporando Receptores de Datos adicionales a medida que crece la confianza
    * [ ] Mantenga procesos de monitoreo y soporte a medida que aumenta el volumen
    * [ ] Documente cualquier lección aprendida para futuras incorporaciones
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Incorporación Regulatoria (Si Aplica)">
    Si su mercado requiere incorporación regulatoria o de registro específica:

    * Trabaje con Fiskil para completar la incorporación con regulador o registro (por ejemplo, ACCC en Australia)
    * Proporcione evidencia de pruebas de conformidad donde se requiera
    * Coordine cronogramas con su equipo de cumplimiento y soporte de Fiskil
    * Valide su Resource Server contra estándares de API relevantes (por ejemplo, CDR, FDX)
    * Capture evidencia de pruebas (registros, métricas, manejo de errores) para revisión regulatoria
  </Accordion>

  <Accordion title="Solución de Problemas en Producción">
    Problemas comunes y soluciones durante ir a producción:

    * **Retrasos de propagación DNS**: Permita 24-48 horas para que los cambios de DNS se propaguen completamente
    * **Validación de certificados**: Asegure que los certificados TLS estén correctamente configurados y no expirados
    * **Fallas de integración de receptores**: Revise registros para problemas de autenticación o alcance
    * **Preocupaciones de rendimiento**: Monitoree métricas y ajuste recursos del ambiente si es necesario
  </Accordion>
</AccordionGroup>

<Note>
  Su ambiente está técnicamente en producción una vez creado. El hito final es **incorporar exitosamente Receptores de Datos** y confirmar patrones de tráfico estables.
</Note>


---

# Preguntas Frecuentes (/es/data-holder/guides/help/faq)

Preguntas comunes sobre la implementación y uso del Proveedor de Datos de Fiskil.



Preguntas Generales [#preguntas-generales]

¿Qué es el Proveedor de Datos de Fiskil? [#qué-es-el-proveedor-de-datos-de-fiskil]

El Proveedor de Datos de Fiskil es una plataforma que permite la compartición segura y compatible de datos entre instituciones financieras y terceros autorizados. Maneja la gestión de consentimientos, validación de tokens y orquestación de API mientras mantiene el cumplimiento regulatorio.

¿Cómo asegura Fiskil la seguridad de los datos? [#cómo-asegura-fiskil-la-seguridad-de-los-datos]

Fiskil implementa múltiples capas de seguridad incluyendo autenticación OAuth 2.0/OIDC, validación de tokens JWT, mTLS opcional y registro completo de auditoría. Toda la transmisión de datos está encriptada y el acceso está estrictamente controlado a través de alcances basados en consentimiento.

¿Qué marcos de cumplimiento soporta Fiskil? [#qué-marcos-de-cumplimiento-soporta-fiskil]

Fiskil soporta diversos marcos regulatorios y estándares del sector, incluidos CDR (Consumer Data Right), FDX (Financial Data Exchange) y PSD2. También permite adaptar la integración a las regulaciones e iniciativas de open banking y open finance de Latinoamérica, incluidas las de Colombia, Chile y Perú.

Los perfiles de cumplimiento pueden configurarse por entorno para responder a los requisitos regulatorios específicos de cada marco y mercado.

Preguntas Técnicas [#preguntas-técnicas]

¿Cómo integro mi Resource Server con Fiskil? [#cómo-integro-mi-resource-server-con-fiskil]

La integración implica configurar los ajustes de su Resource Server en la Consola de Fiskil, implementar validación de tokens JWT y asegurar que sus endpoints de API apliquen los alcances apropiados. Vea nuestra guía de [Inicio Rápido](/es/data-holder/guides/get-started/quickstart) para pasos detallados.

¿Puedo usar dominios personalizados para mi Proveedor de Datos? [#puedo-usar-dominios-personalizados-para-mi-proveedor-de-datos]

Sí, Fiskil soporta dominios personalizados para pantallas de consentimiento, APIs y dashboards del consumidor. Esto asegura una experiencia fluida y con marca para sus clientes. Vea [Dominios Personalizados](/es/data-holder/guides/configure/custom-domains) para instrucciones de configuración.

¿Cómo pruebo mi integración antes de ir a producción? [#cómo-pruebo-mi-integración-antes-de-ir-a-producción]

Fiskil proporciona herramientas de prueba completas incluyendo colecciones de Postman, registros de solicitudes, dashboards de métricas y herramientas de validación de cumplimiento. Siempre pruebe exhaustivamente en staging antes de promover a producción. Vea [Pruebas](/es/data-holder/guides/testing) para más detalles.

Soporte [#soporte]

Para preguntas adicionales o soporte técnico, por favor [contacte a nuestro equipo](https://www.fiskil.com/contact).


---

# AEMO (/es/data-holder/guides/integrations/aemo)

Conéctese con AEMO como Proveedor de Datos Secundario para compartir datos de energía a través de la integración gestionada de Fiskil.



Fiskil proporciona una integración totalmente gestionada con AEMO (Australian Energy Market Operator) como el Proveedor de Datos Secundario para compartir datos de electricidad. Esto incluye uso, DER (Recursos de Energía Distribuida) y acceso a datos de puntos de servicio a través de APIs conformes con el Consumer Data Right (CDR).

***

Qué Está Incluido [#qué-está-incluido]

<CardGroup cols={2}>
  <Card title="Acceso a Datos de Energía" icon="bolt">
    Acceso seguro a datos de uso de electricidad, datos DER e información de puntos de servicio a través de los servicios de Proveedor de Datos Secundario de AEMO.
  </Card>

  <Card title="Credenciales Gestionadas" icon="shield-check">
    Gestión automatizada de credenciales con rotación de contraseñas, verificaciones de salud y notificaciones de vencimiento integradas.
  </Card>
</CardGroup>

Características Principales [#características-principales]

* **Configuración automatizada**: Integración preconfigurada lista para sus necesidades de compartir datos de energía
* **Gestión de credenciales**: Rotación de contraseñas y monitoreo de salud integrados
* **Cumplimiento CDR**: Totalmente conforme con las regulaciones del Consumer Data Right
* **Monitoreo en tiempo real**: Actualizaciones de estado en vivo y alertas automatizadas

***

Comenzando [#comenzando]

<Info>
  La integración con AEMO está disponible como un servicio gestionado a través de Fiskil. Nuestro equipo manejará la configuración técnica y el mantenimiento continuo por usted.
</Info>

¿Listo para habilitar la integración con AEMO para compartir sus datos de energía? Contacte a nuestro equipo de soporte para comenzar:

<Card title="Contactar Soporte" href="https://fiskil.atlassian.net/servicedesk/customer/portal/6" icon="headset">
  Comuníquese con nuestro equipo para habilitar la integración AEMO para su ambiente de Data Provider de Fiskil.
</Card>

***

Lo que Nuestro Equipo Proporciona [#lo-que-nuestro-equipo-proporciona]

<Steps>
  <Step title="Configuración de Integración">
    Configuración completa de conectividad AEMO con su ambiente de Data Provider de Fiskil.
  </Step>

  <Step title="Gestión de Credenciales">
    Rotación automatizada de contraseñas, verificaciones de salud y monitoreo para servicio ininterrumpido.
  </Step>

  <Step title="Soporte Continuo">
    Monitoreo continuo, mantenimiento y soporte técnico para su integración AEMO.
  </Step>
</Steps>

***

Configurando sus credenciales AEMO [#configurando-sus-credenciales-aemo]

Las contraseñas de usuario de AEMO son válidas por 90 días. Después de este período, la contraseña debe restablecerse. Para minimizar el riesgo de tiempo de inactividad durante las rotaciones, recomendamos encarecidamente mantener dos usuarios AEMO activos con el acceso requerido:

<Warning>
  Si solo existe un usuario, las solicitudes pueden fallar entre el restablecimiento de la contraseña en el portal de AEMO y su actualización en la Consola de Fiskil
</Warning>

Al alternar entre dos usuarios, puede evitar este problema. Cuando las credenciales de un usuario están por vencer, cambie al otro antes de realizar un restablecimiento.

Ambos usuarios deben tener acceso de lectura a la entidad de acceso CDR - Energy API en AEMO.

Configurando Usuarios AEMO por Primera Vez [#configurando-usuarios-aemo-por-primera-vez]

Para conectarse con AEMO a través de Fiskil, necesitará crear dos usuarios AEMO con los permisos apropiados. Esta configuración le permite rotar credenciales sin interrupciones de servicio y ayuda a prevenir tiempo de inactividad cuando las contraseñas expiran.

1. Cree su primer usuario a través del portal AEMO MSATs.
2. Otorgue al primer usuario acceso de lectura a CDR - Energy API access.
3. Cree su segundo usuario.
4. Otorgue al segundo usuario el mismo acceso de lectura.
5. Vaya al [menú AEMO](https://console.fiskil.com/data-holder/settings/integrations) en la Consola del Proveedor de Datos.
6. Haga clic en la tarjeta AEMO.
7. Ingrese el nombre de usuario y contraseña para el primer usuario.

<Note>
  Cuando actualiza sus credenciales en la Consola de Fiskil, automáticamente realizamos una verificación de salud de conectividad enviando un ping a AEMO con las nuevas credenciales. Si falla, sus credenciales no se actualizarán.
</Note>

Actualizando la Integración AEMO Durante la Rotación de Contraseña [#actualizando-la-integración-aemo-durante-la-rotación-de-contraseña]

Cuando las credenciales de uno de sus usuarios AEMO están cerca de vencer, siga estos pasos para cambiar al segundo usuario y actualizar las credenciales en la Consola de Fiskil. Esto asegura conectividad continua con AEMO y evita cualquier tiempo de inactividad de API.

1. Restablezca la contraseña para el segundo usuario en el portal de AEMO.
2. Vaya al [menú AEMO](https://console.fiskil.com/data-holder/settings/integrations) en la Consola del Proveedor de Datos.
3. Ingrese las credenciales actualizadas del segundo usuario.

Repita este proceso cuando el próximo usuario esté por vencer. Alternar usuarios asegura compartir datos ininterrumpidamente a través de AEMO.

Detalles de Vencimiento de Credenciales [#detalles-de-vencimiento-de-credenciales]

La fecha de vencimiento mostrada en la consola es un vencimiento estimado calculado como 90 días desde la última actualización de la credencial. Esto puede parecer incorrecto si su credencial fue creada antes pero solo se actualizó en la Consola de Fiskil más recientemente.

Si la consola muestra una fecha futura, refleja cuándo actualizó por última vez la credencial en Fiskil: no necesariamente cuándo se rotó en AEMO.

Múltiples Participantes AEMO [#múltiples-participantes-aemo]

Si su marca usa múltiples IDs de Participante (PIDs), configure un nombre de usuario y contraseña separados para cada PID:

1. Haga clic en Avanzado en el menú de configuración de AEMO.
2. Ingrese el ID de participante, nombre de usuario y contraseña.
3. Haga clic en Agregar Otro Participante si es necesario y repita el paso 2.
4. Haga clic en Guardar.

Aplique la misma estrategia de rotación de dos usuarios a cada participante para evitar tiempo de inactividad. Le recordaremos que actualice sus credenciales cada 90 días.

Credenciales de Pre-Producción [#credenciales-de-pre-producción]

Actualmente, esta función de rotación de credenciales es solo para entornos de producción. Fiskil continuará gestionando las rotaciones de credenciales AEMO de pre-producción en su nombre. Si esto cambia, le notificaremos con anticipación.

Notificaciones [#notificaciones]

Fiskil envía recordatorios de vencimiento de contraseña por correo electrónico a su contacto técnico designado.

El primer correo se envía 10 días antes de la fecha de vencimiento estimada.
Los recordatorios continuarán hasta que las credenciales se actualicen en la Consola de Fiskil.
Asegúrese de que su Contacto Técnico esté correctamente configurado en la Consola en Configuración > Información de la Empresa.

Referencias [#referencias]

* [Guía AEMO de APIs CDR](https://aemo.com.au/-/media/files/initiatives/cdr/guide-to-cdr-apis.pdf?la=en)
* [Guía AEMO de Gestión de Derechos de Usuario](https://aemo.com.au/-/media/files/market-it-systems/guide-to-user-rights-management.pdf)

***

Documentación Relacionada [#documentación-relacionada]

<CardGroup cols={2}>
  <Card title="Referencia API Energy CDR" href="/data-holder/api-reference/cdr-reference" icon="bolt">
    Especificaciones técnicas para endpoints Energy CDR y esquemas de datos.
  </Card>

  <Card title="Configuración de Consola" href="/es/data-holder/guides/configure/custom-domains" icon="gear">
    Aprenda más sobre configurar integraciones y gestionar su ambiente.
  </Card>
</CardGroup>


---

# Gentrack (/es/data-holder/guides/integrations/gentrack)

Conéctese con plataformas de servicios públicos Gentrack a través de Fiskil para compartir datos de energía y servicios públicos de manera conforme.



Fiskil ofrece una integración perfecta con Gentrack, un proveedor líder de soluciones de gestión de clientes y facturación para empresas de energía y servicios públicos. Habilite acceso seguro y consentido a datos de clientes e información de servicios públicos mientras mantiene pleno cumplimiento con las regulaciones de la industria.

***

Qué Está Disponible [#qué-está-disponible]

<CardGroup cols={2}>
  <Card title="Acceso a Datos de Clientes" icon="users">
    Acceda a información de clientes, datos de facturación, patrones de uso y configuraciones de servicio a través de la plataforma de Gentrack.
  </Card>

  <Card title="Listo para Cumplimiento" icon="shield-check">
    Cumplimiento integrado con Consumer Data Right (CDR) y regulaciones de compartir datos de servicios públicos con gobernanza automatizada.
  </Card>
</CardGroup>

Tipos de Datos Soportados [#tipos-de-datos-soportados]

* **Información del cliente**: Perfiles de cuenta, direcciones de servicio y detalles de contacto
* **Datos de facturación y pago**: Historial de facturas, registros de pago y saldos de cuenta
* **Datos de uso de servicios públicos**: Patrones de consumo, lecturas de medidores y uso de servicio
* **Configuraciones de servicio**: Detalles de conexión, información de tarifas y parámetros de servicio

***

Comenzando [#comenzando]

<Info>
  La integración con Gentrack requiere coordinación entre Fiskil, Gentrack y sus equipos técnicos. Nuestros especialistas lo guiarán a través de todo el proceso.
</Info>

¿Listo para conectar su plataforma Gentrack con Fiskil? Contacte a nuestro equipo para comenzar el proceso de integración:

<CardGroup cols={2}>
  <Card title="Contactar Equipo de Integración" href="https://www.fiskil.com/contact" icon="rocket">
    Programe una consulta para discutir sus requisitos y objetivos de integración Gentrack.
  </Card>

  <Card title="Correo a Soporte" href="mailto:support@fiskil.com" icon="envelope">
    Envíe detalles sobre su entorno Gentrack y objetivos de integración a nuestro equipo técnico.
  </Card>
</CardGroup>

***

Cómo Funciona [#cómo-funciona]

Fiskil usa las APIs nativas de Gentrack para facilitar el compartir datos. Simplemente proporcione su ID de cliente y secreto a Fiskil y podemos conectarnos a su entorno Velocity.

Si desea más información sobre cómo funciona la integración, estaremos encantados de conversar con usted y su gerente de cuenta de Gentrack.

<Warning>
  Si necesita soportar Cuentas Complejas CDR, puede que necesite revisar sus mapeos de roles de Velocity
</Warning>

***

Lo que Proporcionamos [#lo-que-proporcionamos]

<Steps>
  <Step title="Configuración de Integración">
    Configuración completa de endpoints de API seguros, gestión de consentimientos e infraestructura de monitoreo.
  </Step>

  <Step title="Pruebas e Ir a Producción">
    Pruebas exhaustivas, validación y soporte continuo para asegurar operación confiable.
  </Step>
</Steps>

<Note>
  El cronograma de integración es típicamente de 6-12 semanas dependiendo de la complejidad de la plataforma y los requisitos de personalización.
</Note>

***

Recursos Adicionales [#recursos-adicionales]

<CardGroup cols={2}>
  <Card title="Referencia Energy CDR" href="/data-holder/api-reference/cdr-reference" icon="lightning-bolt">
    Especificaciones técnicas para estándares e implementaciones de Energy Consumer Data Right.
  </Card>

  <Card title="Configuración de Ambiente" href="/es/data-holder/guides/configure/custom-domains" icon="cog">
    Aprenda cómo configurar y optimizar su Proveedor de Datos de Fiskil para integraciones de servicios públicos.
  </Card>
</CardGroup>


---

# Plaid (/es/data-holder/guides/integrations/plaid)

Conéctese con Plaid, el agregador líder de datos financieros de EE.UU., a través del Proveedor de Datos de Fiskil para compartir datos financieros de forma segura.



Fiskil ofrece una integración integral con Plaid, el agregador de datos financieros líder con sede en EE.UU. Conéctese de forma segura con miles de instituciones financieras para habilitar agregación de cuentas, análisis de transacciones y verificación de identidad mientras mantiene control total sobre los flujos de consentimiento y autorización del usuario.

***

Qué Está Disponible [#qué-está-disponible]

<CardGroup cols={2}>
  <Card title="Acceso a Datos Financieros" icon="building-columns">
    Acceso seguro a datos de cuentas, historial de transacciones, verificación de identidad y datos de ingresos de miles de instituciones financieras de EE.UU.
  </Card>

  <Card title="Seguridad Mejorada" icon="shield-check">
    Capa de autorización conforme con FAPI 2.0 con gestión unificada de consentimiento y monitoreo integral a través de la plataforma de Fiskil.
  </Card>
</CardGroup>

Casos de Uso Principales [#casos-de-uso-principales]

* **Agregación de cuentas**: Acceda a múltiples cuentas bancarias e instituciones financieras
* **Análisis de transacciones**: Obtenga historial de transacciones detallado y categorización
* **Verificación de ingresos**: Verifique los ingresos del usuario para servicios de préstamos y financieros
* **Confirmación de identidad**: Valide la identidad del usuario contra registros bancarios

***

Comenzando [#comenzando]

<Info>
  La integración de Plaid a través de Fiskil requiere coordinación con nuestro equipo técnico para asegurar la configuración adecuada, pruebas y configuración de cumplimiento.
</Info>

¿Listo para integrar Plaid con su Proveedor de Datos de Fiskil? Contacte a nuestro equipo para comenzar el proceso:

<CardGroup cols={2}>
  <Card title="Programar Llamada de Integración" href="https://www.fiskil.com/contact" icon="calendar">
    Reserve una consulta para discutir sus requisitos de integración Plaid y cronograma.
  </Card>

  <Card title="Escribir a Nuestro Equipo" href="mailto:support@fiskil.com" icon="envelope">
    Envíe detalles sobre su caso de uso y requisitos de datos esperados a nuestro equipo de soporte.
  </Card>
</CardGroup>

***

Lo que Proporcionamos [#lo-que-proporcionamos]

<Steps>
  <Step title="Planificación de Integración">
    Revise sus requisitos específicos y planifique la arquitectura de integración con medidas de seguridad apropiadas.
  </Step>

  <Step title="Implementación y Pruebas">
    Configuración completa de endpoints, flujos de consentimiento y pruebas exhaustivas de seguridad y rendimiento.
  </Step>

  <Step title="Soporte de Ir a Producción">
    Despliegue de producción con monitoreo, documentación y soporte continuo para su equipo.
  </Step>
</Steps>

<Note>
  La configuración de integración Plaid típicamente toma de 2-4 semanas dependiendo de la complejidad y los requisitos de prueba.
</Note>

***

Documentación Relacionada [#documentación-relacionada]

<CardGroup cols={2}>
  <Card title="Referencia API FDX" href="/data-holder/api-reference/fdx" icon="book">
    Aprenda sobre estándares FDX y especificaciones de API para compartir datos financieros.
  </Card>

  <Card title="Guía de Inicio" href="/es/data-holder/guides/get-started/quickstart" icon="play">
    Configure su ambiente de Data Provider de Fiskil y configuración básica.
  </Card>
</CardGroup>


---

# Tally Group (/es/data-holder/guides/integrations/tally-group)

Integre con las plataformas de facturación de energía de Tally Group a través de Fiskil para compartir datos de clientes y facturación de forma segura.



Fiskil proporciona una integración integral con Tally Group, el proveedor líder de plataformas de clientes y facturación utilizadas por minoristas de energía en Australia y Nueva Zelanda. Habilite acceso seguro y consentido a datos de clientes e información de facturación mientras mantiene pleno cumplimiento con las regulaciones de compartir datos de energía.

***

Qué Está Disponible [#qué-está-disponible]

<CardGroup cols={2}>
  <Card title="Acceso a Datos de Energía" icon="bolt">
    Acceda a información de cuentas de clientes, datos de facturación, patrones de uso y datos de puntos de servicio a través de la plataforma de Tally Group.
  </Card>

  <Card title="Listo para Cumplimiento" icon="shield-check">
    Cumplimiento integrado con Consumer Data Right (CDR) y regulaciones de compartir datos de energía con gestión automatizada de consentimiento.
  </Card>
</CardGroup>

Tipos de Datos Principales [#tipos-de-datos-principales]

* **Información de cuenta del cliente**: Detalles de cuenta, direcciones de servicio y perfiles de clientes
* **Datos de facturación**: Facturas históricas, información de pagos y ciclos de facturación
* **Datos de uso**: Patrones de consumo de energía y lecturas de medidores
* **Datos de punto de servicio**: Detalles de conexión y configuraciones de servicio

***

Comenzando [#comenzando]

<Info>
  La integración con Tally Group requiere colaboración cercana entre Fiskil, Tally Group y sus equipos técnicos para asegurar la configuración y cumplimiento adecuados.
</Info>

¿Listo para conectar su plataforma Tally Group con Fiskil? Contacte a nuestro equipo para comenzar el proceso de integración:

<CardGroup cols={2}>
  <Card title="Programar Llamada de Descubrimiento" href="https://www.fiskil.com/contact" icon="phone">
    Reserve una consulta para discutir sus requisitos de integración y objetivos de compartir datos.
  </Card>

  <Card title="Escribir al Equipo de Integración" href="mailto:support@fiskil.com" icon="envelope">
    Envíe detalles sobre su configuración actual de Tally Group y objetivos de integración.
  </Card>
</CardGroup>

***

Lo que Proporcionamos [#lo-que-proporcionamos]

<Steps>
  <Step title="Planificación Técnica">
    Evaluación de su configuración de Tally Group y diseño de arquitectura de compartir datos con medidas de seguridad.
  </Step>

  <Step title="Implementación y Pruebas">
    Configuración completa de endpoints seguros, flujos de consentimiento y pruebas exhaustivas de confiabilidad y cumplimiento.
  </Step>

  <Step title="Soporte de Ir a Producción">
    Despliegue de producción con monitoreo, capacitación del equipo y mantenimiento y optimización continuos.
  </Step>
</Steps>

<Note>
  El cronograma de integración es típicamente de 4-8 semanas dependiendo de la complejidad y los requisitos.
</Note>

***

Documentación Relacionada [#documentación-relacionada]

<CardGroup cols={2}>
  <Card title="Visión General Energy CDR" href="/data-holder/api-reference/cdr-reference" icon="zap">
    Aprenda sobre estándares de Energy Consumer Data Right y especificaciones de API.
  </Card>

  <Card title="Configure su Ambiente" href="/es/data-holder/guides/configure/custom-domains" icon="settings">
    Configure y personalice su Proveedor de Datos de Fiskil para compartir datos de energía.
  </Card>
</CardGroup>


---

# Introducción al Data Provider (/es/data-holder/guides/introduction)

Comparta datos de forma segura y con la autorización de sus usuarios. Fiskil gestiona la autorización, los flujos de consentimiento y el cumplimiento normativo para que usted pueda centrarse en su producto.



Fiskil Data Provider permite que su aplicación comparta datos propios con terceros de confianza de forma segura. Nos encargamos de la autorización mediante OpenID Connect, los flujos de consentimiento de los usuarios, la compatibilidad con múltiples entornos y las herramientas operativas, para que su equipo pueda centrarse en el producto y en la experiencia del usuario.

<Cards>
  <Card title="Comenzar a construir" href="/es/data-holder/guides/get-started/quickstart" icon={<DatabaseRestore />} inlineIcon />
</Cards>

<Callout type="info">
  Fiskil cuenta con las certificaciones SOC 2 Tipo 2 y ASAE 3150 Tipo 2. Ofrecemos protección integrada contra ataques DDoS, registros de auditoría seguros y controles de seguridad alineados con los estándares del sector. Obtenga más información en nuestra [descripción general del producto](https://www.fiskil.com/product/data-provider).
</Callout>

***

¿Qué es el intercambio de datos basado en el consentimiento del usuario? [#qué-es-el-intercambio-de-datos-basado-en-el-consentimiento-del-usuario]

El **intercambio de datos basado en el consentimiento del usuario** (User-Permissioned Data Sharing) es un modelo en el que sus clientes mantienen el control sobre sus datos. Los usuarios autorizan expresamente a terceros de confianza (Receptores de Datos) a acceder a conjuntos de datos específicos, para una finalidad y durante un periodo determinados.

A diferencia de los modelos tradicionales —como las exportaciones masivas, las transferencias de archivos o las APIs entre sistemas—, el intercambio de datos basado en el consentimiento del usuario se caracteriza por ser:

* **Basado en consentimiento**: Los usuarios aprueban el acceso mediante flujos de consentimiento alojados
* **Con alcance definido**: Los tokens de acceso incluyen únicamente los permisos otorgados por el usuario
* **Con vigencia limitada**: Los consentimientos expiran automáticamente o pueden revocarse en cualquier momento
* **Auditable**: Toda la actividad queda registrada y vinculada a un consentimiento

Este modelo es la base del Data Provider de Fiskil. Le permite exponer datos propios de forma segura y conforme a la normativa, sin construir usted mismo una infraestructura compleja de autorización y consentimiento.

***

¿Qué es el Data Provider de Fiskil? [#qué-es-el-data-provider-de-fiskil]

El **Data Provider de Fiskil** es la plataforma que convierte a su organización en una **fuente confiable de datos gestionados bajo consentimiento del usuario**.

Usted es el Proveedor de Datos: es propietario de los datos de clientes y productos. Fiskil le da todo lo necesario para exponerlos de forma segura, con consentimiento, autorización y cumplimiento normativo integrados.

Sus responsabilidades principales [#sus-responsabilidades-principales]

Como Proveedor de Datos, usted:

* Implementa el **Resource Server** — las APIs que devuelven datos de clientes y productos
* Define los **conjuntos de datos y scopes** que pueden compartirse

Lo que Fiskil proporciona [#lo-que-fiskil-proporciona]

Fiskil gestiona la infraestructura:

* Aloja los **flujos de consentimiento y dashboards** en su dominio de marca
* Emite y valida tokens alineados con los scopes otorgados
* Proporciona la **consola de gestión, registros de solicitudes y métricas** para su equipo
* Asume la carga operativa del cumplimiento (estándares de autorización, auditoría e informes regulatorios)

¿Por qué elegir Fiskil? [#por-qué-elegir-fiskil]

* **Salida a mercado más rápida**: Lance el intercambio de datos en semanas, no en años
* **Seguridad integrada**: Tokens, validación JWKS, registros de auditoría y protección DDoS
* **Experiencia de usuario gestionada**: Pantallas de consentimiento alojadas y dashboard del consumidor opcional
* **Preparado para estándares internacionales**: diseñado para marcos como CDR y FDX, así como para iniciativas de open banking y open finance en Latinoamérica, incluidas las de Colombia, Chile y Perú.

***

Descripción general de la arquitectura [#descripción-general-de-la-arquitectura]

El Data Provider de Fiskil trabaja junto a su **Resource Server** para ofrecer intercambio de datos seguro y basado en consentimiento. Así se conectan los componentes y quién es responsable de cada uno:

Componentes principales [#componentes-principales]

<Tabs items={["Su Resource Server", "Data Provider de Fiskil", "Receptores de Datos"]}>
  <Tab value="Su Resource Server">
    * Su API que implementa los endpoints de intercambio de datos (p. ej., cuentas, saldos, transacciones)
    * Autentica al Data Provider de Fiskil para asegurar la conexión
    * Devuelve datos de clientes y productos en el formato esperado
  </Tab>

  <Tab value="Data Provider de Fiskil">
    * Servidor de autorización para flujos de consentimiento y emisión de tokens
    * UI de consentimiento alojada y dashboard de consentimiento del consumidor (opcional)
    * Gestión de instancias (staging, producción, multi-región/marca)
    * Autenticación (JWT, JWKS, mTLS opcional)
    * Registros y métricas para observabilidad
  </Tab>

  <Tab value="Receptores de Datos">
    * Aplicaciones o servicios de terceros de confianza que solicitan acceso
    * Integrados de forma directa (personalizada) o vía registros regulatorios (p. ej., receptores acreditados)
    * Usan flujos OAuth2/OIDC para obtener tokens con scopes definidos por el consentimiento del usuario
  </Tab>
</Tabs>

Arquitectura del flujo de datos [#arquitectura-del-flujo-de-datos]

El diagrama siguiente muestra cómo fluyen los datos entre sus clientes, la plataforma Fiskil y las aplicaciones de terceros:

<Mermaid
  chart="sequenceDiagram
  participant C as Sus clientes
  participant F as Data Provider de Fiskil
  participant T as Apps de terceros
  participant R as Su Resource Server

  C->>F: 1. Flujo de consentimiento
  Note over F: UI de consentimiento · Autorización · Cumplimiento
  F->>T: 2. Token de acceso
  T->>R: 3. Llamadas API
  F-->>R: Validación de token
  R->>T: 4. Datos del cliente"
/>

Cómo funciona [#cómo-funciona]

<Steps>
  <Step title="Inicio del consentimiento">
    Un Receptor de Datos inicia un flujo de consentimiento con su cliente.
  </Step>

  <Step title="Autenticación y consentimiento del usuario">
    El servidor de autorización del Data Provider autentica al usuario, presenta pantallas de consentimiento con su marca y captura los scopes aprobados.
  </Step>

  <Step title="Emisión del token">
    Fiskil emite un token de acceso con los scopes específicos otorgados por el usuario.
  </Step>

  <Step title="Acceso a los datos">
    El Receptor de Datos llama a los endpoints de intercambio de datos de Fiskil con el token para acceder a los datos consentidos.
  </Step>

  <Step title="Autorización y respuesta">
    Fiskil valida el token y verifica que la solicitud esté autorizada antes de obtener los datos del cliente desde su Resource Server.
  </Step>

  <Step title="Monitoreo y cumplimiento">
    Toda la actividad se registra en Request Logs y se refleja en Metrics para monitoreo y auditoría.
  </Step>
</Steps>

División de responsabilidades [#división-de-responsabilidades]

<Cards>
  <Card title="Usted (Proveedor de Datos)" icon={<DatabaseRestore />}>
    Construye y mantiene su Resource Server.
  </Card>

  <Card title="Fiskil" icon={<Building />}>
    Proporciona la infraestructura del Data Provider: flujos de consentimiento, tokens, AuthN/AuthZ, observabilidad y herramientas listas para cumplimiento.
  </Card>

  <Card title="Receptores de Datos" icon={<Phone />}>
    Construyen integraciones con sus datos bajo el consentimiento del usuario.
  </Card>
</Cards>

***

Cómo encaja Fiskil en su arquitectura [#cómo-encaja-fiskil-en-su-arquitectura]

* Su equipo construye y gestiona un `Resource Server`, que implementa las APIs para exponer sus datos
* Fiskil proporciona:
  * Un servidor de autorización y de recursos compatible con FAPI 2.0
  * Flujos de consentimiento totalmente gestionados
  * Entornos de staging y producción
  * Una consola de gestión para observabilidad, configuración y herramientas
* Los terceros acceden a los datos mediante onboarding directo o a través de marcos de receptores registrados (p. ej., CDR, FDX)

Entornos [#entornos]

Cada integración se ejecuta en **instancias** aisladas:

* **Staging**: para desarrollo, integración y pruebas con receptores mock
* **Production**: para tráfico en vivo y regulado
* Pueden crearse instancias adicionales para despliegues multi-marca o multi-región

<Callout type="idea">
  Más información sobre la configuración de entornos en la [guía de Instances](/es/data-holder/guides/get-started/instances).
</Callout>

***

Capacidades clave [#capacidades-clave]

<AccordionGroup>
  <Accordion title="Autorización de grado financiero">
    Implementación certificada de OpenID Connect FAPI 2.0, con protección robusta para datos sensibles.
  </Accordion>

  <Accordion title="Gestión de consentimientos">
    Sistema completo para crear, consultar y revocar consentimientos de usuario vía API o componentes de UI preconstruidos.
  </Accordion>

  <Accordion title="Observabilidad y auditoría">
    Registros de tráfico en tiempo real, métricas de disponibilidad y trazas de auditoría para visibilidad total de las actividades de intercambio de datos.
  </Accordion>

  <Accordion title="Onboarding de terceros">
    Incorpore receptores externos de forma directa o integre con registros regulatorios de intercambio de datos.
  </Accordion>

  <Accordion title="Soporte de cuentas complejas">
    Soporte para cuentas organizacionales, conjuntas y multipartitas, con gestión flexible de permisos.
  </Accordion>

  <Accordion title="Estándares globales de intercambio de datos">
    Compatibilidad con estándares y marcos como Consumer Data Right (CDR) y Financial Data Exchange (FDX), así como con iniciativas de open banking y open finance en Latinoamérica, incluidas las de Colombia, Chile y Perú.
  </Accordion>

  <Accordion title="Intercambio de productos y metadatos">
    Exponga esquemas de productos y metadatos junto con los datos específicos del cliente.
  </Accordion>

  <Accordion title="Reportes regulatorios">
    Flujos de trabajo alineados con las obligaciones de cumplimiento e informes de su jurisdicción.
  </Accordion>
</AccordionGroup>

***

Comenzar [#comenzar]

Elija cómo desea iniciar su integración:

<Cards>
  <Card title="Desplegar su primer tenant" href="/es/data-holder/guides/get-started/instances" icon={<DatabaseRestore />}>
    Configure entornos de staging y producción para su integración de intercambio de datos.
  </Card>

  <Card title="Construir su Resource Server" href="/es/data-holder/guides/build/resource-server" icon={<Building />}>
    Implemente las APIs que expondrán los datos de sus clientes y productos.
  </Card>

  <Card title="Seguir un marco regulatorio" href="/es/data-holder/guides/integrations/plaid" icon={<Phone />}>
    Integre con marcos establecidos como CDR, FDX u open banking LATAM.
  </Card>
</Cards>

***

Manténgase al día [#manténgase-al-día]

<Cards>
  <Card title="Leer nuestro blog" href="https://www.fiskil.com/blog" icon={<DatabaseRestore />}>
    Manténgase al día con las mejores prácticas e insights sobre intercambio de datos.
  </Card>

  <Card title="Suscribirse al newsletter" href="https://www.fiskil.com/newsletter" icon={<Phone />}>
    Reciba actualizaciones de producto y noticias del sector en su bandeja de entrada.
  </Card>
</Cards>


---

# API de Grado Financiero (FAPI) (/es/data-holder/guides/security/fapi)

Cómo Fiskil implementa el FAPI 2.0 Security Profile y el perfil de Message Signing para proteger el intercambio de datos financieros con mTLS, PAR, DPoP y PKCE.



Fiskil implementa el [FAPI 2.0 Security Profile](https://openid.net/wg/fapi/) para clientes confidenciales, incluyendo PAR, PKCE con S256, identificación del emisor, tokens de acceso vinculados al remitente usando mTLS o DPoP, y autenticación de cliente usando mTLS o `private_key_jwt`. Cuando lo requiere un ecosistema, Fiskil también soporta el perfil separado de FAPI 2.0 Message Signing, incluyendo JAR y JARM.

***

Por qué FAPI es importante [#por-qué-fapi-es-importante]

El perfil de seguridad **Financial-grade API (FAPI)**, desarrollado por la OpenID Foundation, define el estándar más alto para asegurar el intercambio de datos basado en APIs. Fue creado específicamente para escenarios donde los datos son sensibles y los riesgos son altos — banca, energía, salud y finanzas abiertas.

Los flujos estándar de OAuth 2.0 fueron diseñados para inicio de sesión social y delegación de bajo riesgo. FAPI cierra las brechas de seguridad que importan para datos financieros: robo de tokens, interceptación de códigos de autorización, manipulación de solicitudes y phishing. Los marcos regulatorios alrededor del mundo — incluyendo el Consumer Data Right de Australia, Open Finance Brasil y UK Open Banking — exigen o referencian fuertemente el cumplimiento de FAPI.

**El Data Provider de Fiskil implementa FAPI 2.0 de forma nativa.** Cuando conecta su Servidor de Recursos a Fiskil, cada flujo de autorización, intercambio de tokens y llamada a la API está automáticamente protegido por el perfil de seguridad FAPI completo. Su equipo de ingeniería se enfoca en exponer datos; Fiskil maneja la infraestructura de seguridad.

***

La pila de protocolos FAPI 2.0 [#la-pila-de-protocolos-fapi-20]

FAPI 2.0 no es un protocolo independiente — es un **perfil de seguridad** que restringe y fortalece OAuth 2.0 y OpenID Connect. Piense en él como un conjunto estricto de reglas sobre estándares existentes. Así se componen las capas:

<ProtocolStack />

<Callout type="info">
  **Punto clave:** Fiskil es dueño de cada capa de la pila de seguridad sobre su Servidor de Recursos. Usted implementa una API REST estándar y valida JWTs — Fiskil maneja la complejidad específica de FAPI: pushed authorization requests, tokens vinculados al remitente, gestión de certificados de clientes y cumplimiento de consentimiento.
</Callout>

Arquitectura del sistema [#arquitectura-del-sistema]

El diagrama a continuación muestra cómo Fiskil se sitúa entre los Receptores de Datos y su Servidor de Recursos, gestionando la capa completa de seguridad FAPI.

<ArchitectureDiagram />

***

Mecanismos de seguridad FAPI 2.0 [#mecanismos-de-seguridad-fapi-20]

Security Profile (Requisitos base) [#security-profile-requisitos-base]

El FAPI 2.0 Security Profile exige los siguientes mecanismos para todos los clientes confidenciales. Cada uno aborda un vector de ataque específico en el intercambio de datos financieros.

| Mecanismo                                        | Amenaza mitigada                                                                              | Implementación de Fiskil                                                                                                                                                                                                         |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PAR** (Pushed Authorization Requests)          | Manipulación de parámetros de autorización, phishing mediante URIs de redirección manipuladas | Todas las solicitudes de autorización se envían servidor a servidor al endpoint `/par` antes de que el usuario sea redirigido. El navegador solo ve un `request_uri` opaco — ningún parámetro sensible está expuesto.            |
| **Tokens vinculados al remitente vía mTLS**      | Robo de tokens, suplantación, ataques man-in-the-middle                                       | Fiskil vincula los tokens de acceso al certificado X.509 del cliente. Los tokens son inutilizables sin la clave privada correspondiente. La gestión de certificados es manejada por Fiskil para Receptores de Datos registrados. |
| **Tokens vinculados al remitente vía DPoP**      | Exfiltración y repetición de tokens                                                           | Una alternativa a la vinculación basada en mTLS para clientes confidenciales. Los clientes incluyen un JWT de prueba firmado con cada solicitud, vinculando el token a un par de claves específico.                              |
| **PKCE** (Proof Key for Code Exchange)           | Interceptación de código de autorización                                                      | Cada flujo de autorización usa PKCE con el método de desafío `S256`. El código de autorización está vinculado al cliente original y no puede ser intercambiado por un atacante.                                                  |
| **`private_key_jwt`** (Autenticación de cliente) | Filtración de secretos de cliente, credential stuffing                                        | Los clientes se autentican en el endpoint de tokens usando un JWT firmado con su clave privada. Ningún secreto compartido se transmite por la red.                                                                               |
| **Identificación del emisor**                    | Ataques de confusión de servidor de autorización                                              | El parámetro `iss` se incluye en las respuestas de autorización, permitiendo a los Receptores de Datos verificar qué servidor de autorización emitió la respuesta.                                                               |

Perfil de Message Signing (Requisitos del ecosistema) [#perfil-de-message-signing-requisitos-del-ecosistema]

El perfil de FAPI 2.0 Message Signing es un perfil de conformidad separado que agrega no repudio al intercambio de autorización. Fiskil soporta Message Signing cuando lo requiere un ecosistema.

| Mecanismo                                             | Amenaza mitigada                                     | Implementación de Fiskil                                                                                                                                                                  |
| ----------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **JAR** (JWT-Secured Authorization Request, RFC 9101) | Inyección de parámetros, modificación de solicitudes | Los parámetros de solicitud de autorización se empaquetan como un JWT firmado (usando PS256), asegurando que el servidor de autorización procese exactamente lo que el cliente pretendía. |
| **JARM** (JWT Secured Authorization Response Mode)    | Manipulación de respuestas de autorización           | Las respuestas de autorización se devuelven como JWTs firmados en lugar de parámetros URL simples. Los Receptores de Datos pueden verificar la integridad y autenticidad de la respuesta. |

***

Flujo de autorización [#flujo-de-autorización]

La siguiente secuencia muestra cómo Fiskil orquesta un flujo de autorización FAPI 2.0 entre un Receptor de Datos (aplicación de terceros), el Data Provider de Fiskil (servidor de autorización) y su Servidor de Recursos.

<Mermaid
  chart="sequenceDiagram
    participant DR as Receptor de Datos
    participant F as Fiskil Data Provider
    participant U as Usuario (Navegador)
    participant RS as Su Servidor de Recursos

    Note over DR,F: 1. Pushed Authorization Request
    DR->>F: POST /connect/par (private_key_jwt)
    F-->>DR: request_uri

    Note over DR,U: 2. Redirección del usuario
    DR->>U: Redirigir a /connect/authorize?request_uri=...&client_id=...
    U->>F: Solicitud de autorización (sin parámetros sensibles en URL)

    Note over F,RS: 3. Autenticación y consentimiento
    F->>RS: Obtener lista de cuentas (autenticado por JWT)
    RS-->>F: Cuentas del cliente
    F->>U: Presentar pantalla de consentimiento
    U->>F: Aprobar intercambio de datos

    Note over F,DR: 4. Código de autorización
    F->>U: Redirigir con código de autorización + parámetro iss
    U->>DR: Código de autorización (vinculado a PKCE)

    Note over DR,F: 5. Intercambio de tokens
    DR->>F: POST /connect/token (código + verificador PKCE + private_key_jwt)
    F-->>DR: Token de acceso vinculado (mTLS/DPoP) + token de ID

    Note over DR,RS: 6. Acceso a datos
    DR->>F: Solicitud API con token vinculado
    F->>F: Validar vinculación de token + scope de consentimiento
    F->>RS: Reenviar solicitud (JWT de corta duración)
    RS-->>F: Datos del cliente
    F-->>DR: Respuesta de datos"
/>

<Steps>
  <Step title="Pushed Authorization Request">
    El Receptor de Datos envía parámetros de autorización directamente al endpoint `/par` de Fiskil usando autenticación `private_key_jwt`. Fiskil valida la identidad del cliente, almacena la solicitud y devuelve un `request_uri` opaco.

    **Receptor de Datos → Fiskil** (servidor a servidor)
  </Step>

  <Step title="Redirección del usuario a autorización">
    El Receptor de Datos redirige el navegador del usuario al endpoint de autorización de Fiskil con solo el `request_uri` y `client_id`. Ningún parámetro sensible es visible en la URL.

    **Receptor de Datos → Navegador → Fiskil**
  </Step>

  <Step title="Autenticación y consentimiento">
    Fiskil autentica al usuario final (a través de su integración de verificación de identidad), presenta pantallas de consentimiento con marca mostrando los scopes y datos solicitados, y captura la aprobación del usuario. Fiskil llama a su Servidor de Recursos para obtener las listas de cuentas para la pantalla de consentimiento.

    **Usuario ↔ Fiskil**, **Fiskil → Su Servidor de Recursos**
  </Step>

  <Step title="Código de autorización emitido">
    Fiskil redirige al usuario de vuelta al Receptor de Datos con un código de autorización de un solo uso y el parámetro `iss` identificando el servidor de autorización. El código está vinculado al desafío PKCE enviado en el paso 1. Cuando Message Signing está habilitado, la respuesta se devuelve como un JWT firmado vía JARM.

    **Fiskil → Navegador → Receptor de Datos**
  </Step>

  <Step title="Intercambio de tokens">
    El Receptor de Datos intercambia el código de autorización en el endpoint de tokens de Fiskil, autenticándose con `private_key_jwt` y presentando el verificador PKCE. Fiskil emite un **token de acceso vinculado al remitente** (vinculado mediante certificado mTLS o clave DPoP) y un token de ID.

    **Receptor de Datos → Fiskil** (vinculado por mTLS / DPoP)
  </Step>

  <Step title="Acceso a datos">
    El Receptor de Datos presenta el token de acceso vinculado al remitente a los endpoints de intercambio de datos de Fiskil. Fiskil valida la vinculación del token (huella del certificado mTLS o prueba DPoP), verifica el scope del consentimiento y llama a su Servidor de Recursos con un JWT de corta duración para obtener los datos.

    **Receptor de Datos → Fiskil → Su Servidor de Recursos**
  </Step>
</Steps>

<Callout type="info">
  **Su punto de integración:** Los pasos 3 y 6 son donde Fiskil llama a su Servidor de Recursos. Usted valida el JWT emitido por Fiskil (usando su endpoint JWKS) y devuelve los datos solicitados. Todo lo demás — PAR, PKCE, mTLS, vinculación de tokens, gestión de consentimiento — es manejado por Fiskil.
</Callout>

***

Lo que usted implementa vs. lo que Fiskil maneja [#lo-que-usted-implementa-vs-lo-que-fiskil-maneja]

<Cards>
  <Card title="Fiskil gestiona" icon={<ShieldCheck />}>
    Servidor de autorización FAPI 2.0, endpoint PAR, endpoint de tokens, terminación mTLS, validación DPoP, aplicación de PKCE, identificación del emisor, pantallas de consentimiento, ciclo de vida del consentimiento, registros de auditoría, onboarding de Receptores de Datos, gestión de certificados, hosting JWKS, correlación `x-fapi-interaction-id` y reportes regulatorios. Cuando Message Signing es requerido: validación JAR y firma JARM.
  </Card>

  <Card title="Usted construye" icon={<Code />}>
    Un Servidor de Recursos que expone endpoints de datos de clientes y valida JWTs emitidos por Fiskil usando su endpoint JWKS. Tres endpoints de autenticación (`/customer/search`, `/customer/{id}`, `/customer/{id}/accounts`) más sus APIs de datos. Opcionalmente, una lista de IPs permitidas para las IPs de egreso de Fiskil.
  </Card>
</Cards>

***

Seguridad de tokens en profundidad [#seguridad-de-tokens-en-profundidad]

El robo de tokens es el principal vector de ataque en el intercambio de datos basado en APIs. FAPI 2.0 aborda esto a través de **tokens vinculados al remitente** — tokens que están criptográficamente vinculados al cliente que los solicitó, haciendo que los tokens robados sean inútiles para un atacante.

Vinculación de certificados mTLS [#vinculación-de-certificados-mtls]

Cuando un Receptor de Datos se autentica con TLS mutuo, Fiskil registra la huella SHA-256 del certificado X.509 del cliente en el claim `cnf` (confirmación) del token de acceso. En cada llamada API posterior, Fiskil verifica que el certificado del cliente que presenta coincida con la huella incorporada en el token. Si el certificado no coincide, la solicitud es rechazada — incluso si el token en sí es válido.

```json
{
  "iss": "https://cdr.acme-bank.fiskil.com",
  "sub": "client_abc123",
  "scope": "accounts:read balances:read",
  "exp": 1700000000,
  "cnf": {
    "x5t#S256": "hL2FQIO7Yb...certificate-thumbprint"
  }
}
```

DPoP (Demonstration of Proof-of-Possession) [#dpop-demonstration-of-proof-of-possession]

Para clientes confidenciales que no pueden usar mTLS (entornos sin infraestructura de certificados de cliente), Fiskil soporta DPoP como mecanismo alternativo de vinculación al remitente. El cliente genera un par de claves efímero e incluye un JWT de prueba firmado en el encabezado `DPoP` de cada solicitud. El token de acceso incluye un claim de confirmación `jkt` (JWK Thumbprint) vinculándolo a la clave pública del cliente.

```http
POST /connect/token HTTP/2
Host: secure.acme-bank.fiskil.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0Iiw...

grant_type=authorization_code
&code=auth_code_here
&code_verifier=pkce_verifier
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJ...
```

***

Encabezados FAPI y correlación de solicitudes [#encabezados-fapi-y-correlación-de-solicitudes]

Fiskil soporta los encabezados de interacción FAPI estándar en todas las superficies de API, proporcionando trazabilidad de extremo a extremo para cada solicitud en la cadena de intercambio de datos.

| Encabezado                   | Dirección             | Propósito                                                                                                                                                                                                       |
| ---------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-fapi-interaction-id`      | Solicitud y Respuesta | ID de correlación UUID que fluye desde el Receptor de Datos a través de Fiskil hasta su Servidor de Recursos y de vuelta. Permite el rastreo de solicitudes de extremo a extremo entre todos los participantes. |
| `x-fapi-auth-date`           | Solicitud             | Marca de tiempo del último evento de autenticación del usuario. Utilizado por el servidor de autorización para evaluar requisitos de autenticación escalonada.                                                  |
| `x-fapi-customer-ip-address` | Solicitud             | La dirección IP del usuario final. Reenviada para detección de fraude y propósitos de auditoría, soportando decisiones de acceso basadas en riesgo.                                                             |

***

OAuth 2.0 estándar vs. FAPI 2.0 [#oauth-20-estándar-vs-fapi-20]

Para entender el valor que agrega FAPI, es útil contrastarlo con una implementación estándar de OAuth 2.0.

| Aspecto                      | OAuth 2.0 estándar                                       | FAPI 2.0 (Fiskil)                                                                                   |
| ---------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Solicitud de autorización    | Parámetros en la cadena de consulta URL                  | Parámetros enviados servidor a servidor vía PAR; el navegador solo ve `request_uri`                 |
| Autenticación de cliente     | `client_secret_post` o `client_secret_basic`             | `private_key_jwt` o `tls_client_auth` — sin secretos compartidos                                    |
| Vinculación de tokens        | Tokens Bearer (utilizables por cualquiera que los tenga) | Tokens vinculados al remitente (vinculados por mTLS o DPoP)                                         |
| Protección de código de auth | PKCE opcional                                            | PKCE obligatorio con S256                                                                           |
| Respuesta de autorización    | Parámetros URL simples                                   | Incluye parámetro `iss` para identificación del servidor. Con Message Signing: JWT firmado vía JARM |
| Seguridad de transporte      | TLS (autenticado por servidor)                           | TLS con autenticación mutua opcional (mTLS)                                                         |
| Rastreo de solicitudes       | Sin estándar                                             | Correlación de extremo a extremo `x-fapi-interaction-id`                                            |

***

Firma de mensajes FAPI 2.0 [#firma-de-mensajes-fapi-20]

La especificación FAPI 2.0 define dos perfiles de conformidad distintos: el **Security Profile** y el perfil de **Message Signing**. El Security Profile (cubierto en las secciones anteriores) maneja el fortalecimiento del flujo de autorización, la vinculación de tokens y la autenticación de clientes. El perfil de Message Signing agrega una capa separada de no repudio — prueba criptográfica de que un mensaje específico fue enviado por una parte específica y no ha sido manipulado.

Cómo funciona [#cómo-funciona]

Message Signing usa dos mecanismos complementarios. **JAR (JWT-Secured Authorization Request, RFC 9101)** requiere que los parámetros de solicitud de autorización se empaqueten como un JWT firmado antes del envío. Esto asegura que el servidor de autorización procese exactamente lo que el cliente pretendía — ningún parámetro puede ser agregado, eliminado o modificado en tránsito. **JARM (JWT-Secured Authorization Response Mode)** aplica el mismo principio a la inversa: las respuestas de autorización se devuelven como JWTs firmados, permitiendo al cliente verificar que la respuesta provino del servidor de autorización legítimo y no fue interceptada o alterada.

Juntos, JAR y JARM crean una **cadena de mensajes firmados** a lo largo de todo el intercambio de autorización. Esto es particularmente importante en finanzas abiertas, donde los marcos regulatorios pueden requerir evidencia de auditoría de que ambas partes en un acuerdo de intercambio de datos pueden probar exactamente qué se solicitó y qué se autorizó.

<Cards>
  <Card title="JAR — Firma de solicitudes" icon={<ArrowUp />}>
    Los parámetros de solicitud de autorización son firmados por el Receptor de Datos usando su clave privada (PS256). Fiskil valida la firma contra el JWKS registrado del Receptor de Datos antes de procesar la solicitud. Previene la inyección de parámetros de solicitud y proporciona no repudio de la solicitud de autorización.
  </Card>

  <Card title="JARM — Firma de respuestas" icon={<ArrowDown />}>
    Las respuestas de autorización son firmadas por Fiskil usando ES256. Los Receptores de Datos validan la firma contra el JWKS publicado de Fiskil. Previene la manipulación de respuestas de autorización y proporciona prueba criptográfica de la decisión de autorización.
  </Card>
</Cards>

<Callout type="info">
  Fiskil soporta tanto el Security Profile como el perfil de Message Signing. JAR y JARM están habilitados por defecto para todas las instancias de Data Provider. Los Receptores de Datos que requieren conformidad con Message Signing pueden confiar en el servidor de autorización de Fiskil para manejar tanto la validación de solicitudes como la firma de respuestas sin configuración adicional en su Servidor de Recursos.
</Callout>

***

Descubrimiento y endpoints well-known [#descubrimiento-y-endpoints-well-known]

Fiskil publica metadatos estándar de OpenID Connect Discovery en el endpoint `/.well-known/openid-configuration` para cada instancia de Data Provider. Los Receptores de Datos utilizan esto para configurar automáticamente su integración sin codificar endpoints.

Los metadatos a continuación están anotados para distinguir los campos del Security Profile base de los campos de Message Signing.

```json
{
  "issuer": "https://public.acme-bank.prod.provider.fiskil.com",
  "authorization_endpoint": "https://public.acme-bank.prod.provider.fiskil.com/connect/authorize",
  "token_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/connect/token",
  "introspection_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/connect/introspect",
  "revocation_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/revoke",
  "userinfo_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/userinfo",
  "registration_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/connect/register",
  "jwks_uri": "https://public.acme-bank.prod.provider.fiskil.com/jwks",
  "pushed_authorization_request_endpoint": "https://secure.acme-bank.prod.provider.fiskil.com/connect/par"
}
```

**Campos del Security Profile:**

```json
{
  "require_pushed_authorization_requests": true,
  "tls_client_certificate_bound_access_tokens": true,
  "authorization_response_iss_parameter_supported": true,
  "code_challenge_methods_supported": ["S256"],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "subject_types_supported": ["pairwise"],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "tls_client_auth",
    "self_signed_tls_client_auth"
  ],
  "token_endpoint_auth_signing_alg_values_supported": ["ES256", "PS256"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "dpop_signing_alg_values_supported": ["ES256", "PS256"],
  "claims_parameter_supported": true,
  "scopes_supported": ["openid", "profile", "accounts:read", "..."],
  "claims_supported": [
    "name", "given_name", "family_name", "sharing_duration",
    "iss", "sub", "aud", "acr", "exp", "iat", "nonce",
    "auth_time", "updated_at"
  ]
}
```

**Campos del perfil de Message Signing** (presentes cuando el ecosistema requiere JAR/JARM):

```json
{
  "response_modes_supported": ["jwt"],
  "require_signed_request_object": true,
  "request_object_signing_alg_values_supported": ["PS256", "ES256"],
  "authorization_signing_alg_values_supported": ["ES256", "PS256"]
}
```

<Callout type="info">
  Cada instancia de Data Provider tiene su propio endpoint de descubrimiento con URLs específicas de la instancia. El ejemplo anterior muestra la estructura general — sus endpoints reales usarán su subdominio de marca (por ejemplo, `public.acme-bank.prod.provider.fiskil.com`). Los campos de Message Signing se incluyen cuando el ecosistema requiere conformidad con JAR y JARM.
</Callout>

***

Certificaciones y cumplimiento [#certificaciones-y-cumplimiento]

Fiskil se somete a auditorías de seguridad independientes y mantiene certificaciones que complementan el cumplimiento de FAPI.

<Cards>
  <Card title="SOC 2 Type 2" icon={<ShieldCheck />}>
    Auditoría independiente de controles de seguridad, disponibilidad y confidencialidad en la infraestructura y prácticas de manejo de datos de Fiskil.
  </Card>

  <Card title="ASAE 3150 Type 2" icon={<ClipboardCheck />}>
    Estándar australiano de aseguramiento para controles relevantes al manejo de datos. Requerido para CDR Data Holders que operan en Australia.
  </Card>

  <Card title="Conformidad OpenID" icon={<Lock />}>
    El servidor de autorización de Fiskil está certificado contra la suite de conformidad FAPI de la OpenID Foundation.
  </Card>

  <Card title="Protección DDoS" icon={<Globe />} href="/es/data-holder/guides/security/firewall">
    Mitigación DDoS, bloqueo de IPs maliciosas y limitación de receptores mediante Fiskil Firewall.
  </Card>
</Cards>

***

Preguntas frecuentes [#preguntas-frecuentes]

<AccordionGroup>
  <Accordion title="¿Necesito implementar mTLS en mi Servidor de Recursos?">
    No. mTLS se aplica entre los Receptores de Datos y el servidor de autorización de Fiskil. Fiskil se autentica con su Servidor de Recursos usando JWTs firmados (validados vía JWKS). Opcionalmente puede agregar una lista de IPs permitidas para las IPs de egreso de Fiskil como capa de seguridad adicional.
  </Accordion>

  <Accordion title="¿Qué mecanismo de vinculación al remitente deben usar los Receptores de Datos?">
    Fiskil soporta tanto mTLS como DPoP para clientes confidenciales. mTLS es requerido para marcos regulatorios como el CDR de Australia. DPoP está disponible para entornos de clientes confidenciales donde la infraestructura de certificados de cliente es impracticable. El proceso de onboarding de Fiskil ayuda a los Receptores de Datos a elegir el mecanismo adecuado para su caso de uso.
  </Accordion>

  <Accordion title="¿Fiskil soporta FAPI 1.0 Advanced?">
    Sí. Fiskil soporta el perfil FAPI 1.0 Advanced para implementaciones existentes en ecosistemas que lo requieren. FAPI 2.0 es el predeterminado para nuevas integraciones y es el perfil sucesor recomendado por la OpenID Foundation. Fiskil gestiona la ruta de migración para clientes en transición entre versiones.
  </Accordion>

  <Accordion title="¿Cómo interactúa FAPI con diferentes estándares de datos (CDR, Open Finance)?">
    FAPI define la capa de seguridad — cómo funcionan la autorización, autenticación y vinculación de tokens. Los estándares de datos como CDR y Open Finance definen el modelo de datos y los contratos de API. Fiskil implementa ambas capas: el perfil de seguridad FAPI a nivel del servidor de autorización, y los esquemas de API específicos del estándar en la capa de intercambio de datos. Su Servidor de Recursos implementa los endpoints de datos para el estándar elegido.
  </Accordion>

  <Accordion title="¿Puedo usar Fiskil para intercambio de datos no regulados?">
    Sí. El modo Bring Your Own Data (BYOD) de Fiskil le permite compartir cualquier conjunto de datos a través de la misma infraestructura asegurada por FAPI. Incluso cuando no se requiere cumplimiento regulatorio, los beneficios de seguridad de FAPI (tokens vinculados al remitente, PAR, PKCE) protegen sus datos y sus clientes.
  </Accordion>

  <Accordion title="¿Cómo se compara esto con construir con Auth0 u Okta?">
    Las plataformas de identidad de propósito general como Auth0 y Okta proporcionan bloques de construcción de OAuth 2.0 y OpenID Connect. El cumplimiento de FAPI requiere configuración adicional significativa: habilitar PAR, configurar terminación mTLS, implementar tokens vinculados al remitente, gestionar certificados de Receptores de Datos y construir flujos de consentimiento. Fiskil proporciona todo esto como un servicio gestionado, construido específicamente para el intercambio de datos en finanzas abiertas — sin ensamblaje requerido.
  </Accordion>
</AccordionGroup>

***

Recursos [#recursos]

<Cards>
  <Card title="Guía de autenticación" href="/es/data-holder/guides/build/jwt-security">
    Configure la validación de tokens y JWKS para su Servidor de Recursos.
  </Card>

  <Card title="Inicio rápido de integración" href="/es/data-holder/guides/get-started/quickstart">
    Guía paso a paso para construir su integración con Fiskil.
  </Card>

  <Card title="Especificación FAPI de OpenID" href="https://openid.net/wg/fapi/">
    Documentación oficial del grupo de trabajo FAPI de la OpenID Foundation.
  </Card>
</Cards>


---

# Firewall (/es/data-holder/guides/security/firewall)

Cómo Fiskil Firewall limita a los receptores de datos, mitiga DDoS y bloquea tráfico malicioso antes de que llegue a su Resource Server.



Fiskil Firewall se sitúa frente a su Data Provider y protege su Resource Server frente a carga ilimitada de terceros, ataques de denegación de servicio y tráfico desde IPs maliciosas. Los receptores de datos llaman a Fiskil — no directamente a su Resource Server —, por lo que estos controles se aplican en el edge antes de reenviar cualquier solicitud.

***

Qué cubre Fiskil Firewall [#qué-cubre-fiskil-firewall]

<CardGroup cols={3}>
  <Card title="Limitación de receptores" icon="gauge-high">
    Limita el tráfico de receptores de datos terceros según los estándares de open finance.
  </Card>

  <Card title="Protección DDoS" icon="shield">
    Mitiga ataques de denegación de servicio volumétricos y de capa de aplicación en endpoints de autorización e intercambio de datos.
  </Card>

  <Card title="Bloqueo de IPs maliciosas" icon="ban">
    Detecta y bloquea direcciones IP abusivas o conocidas como maliciosas antes de que lleguen a sus sistemas.
  </Card>
</CardGroup>

Cuando el Firewall rechaza una solicitud, **no** se reenvía a su Resource Server. No necesita implementar limitación de velocidad por receptor ni controles DDoS de edge en su Resource Server para el tráfico de open finance.

***

Limitación de receptores [#limitación-de-receptores]

Fiskil limita automáticamente a los receptores de datos terceros para que pueda planificar la capacidad de su Resource Server frente a un margen predecible.

La configuración **por defecto** de Fiskil limita cada receptor de datos a **50 TPS**. Cuando un receptor supera el umbral configurado, Fiskil rechaza la llamada (normalmente con `429 Too Many Requests`) y no la reenvía a su Resource Server.

<Callout type="info">
  Los umbrales de tráfico de open finance varían según el mercado. Fiskil actualiza la configuración del Firewall por entorno para alinearla con los estándares aplicables a ese despliegue. Trate 50 TPS como el valor por defecto de la plataforma, no como un límite global fijo.
</Callout>

***

DDoS y tráfico malicioso [#ddos-y-tráfico-malicioso]

Además de la limitación de receptores, Fiskil Firewall ofrece protección continua frente a tráfico abusivo:

* **Mitigación DDoS** en endpoints de autorización e intercambio de datos, con análisis automático de tráfico y limitación de velocidad
* **Detección de IPs maliciosas y abusivas**, bloqueando orígenes que intentan agotar capacidad o sondear su Data Provider
* **Moldeado de tráfico** para que ráfagas cortas o un uso irrazonable de un solo cliente no priven de capacidad al intercambio de datos legítimo

Esto coincide con la protección de edge descrita en el [producto Data Provider](https://www.fiskil.com/product/data-provider): defensa integrada para que su equipo se centre en servir datos con consentimiento, no en absorber tráfico de ataque a escala de internet.

***

Planificación de capacidad [#planificación-de-capacidad]

Use el margen del Firewall al dimensionar su Resource Server:

* **Carga por receptor** — con el valor por defecto de la plataforma, un solo receptor de datos no debería enviar más de \~50 TPS de tráfico reenviado; confirme el límite configurado en su entorno si su mercado difiere
* **Múltiples receptores** — la carga total puede crecer con el número de receptores activos; dimensione para receptores concurrentes más margen operativo
* **SLAs de rendimiento** — los requisitos de tiempo de respuesta de su régimen de open finance siguen aplicando al tráfico permitido

Supervise [métricas](/es/data-holder/guides/telemetry/metrics) como TPS pico, TPS promedio y rechazos para validar el tráfico real frente a su modelo de capacidad.

***

Relacionado [#relacionado]

<Cards>
  <Card title="Seguridad FAPI" href="/es/data-holder/guides/security/fapi">
    Autorización de grado financiero, certificaciones y controles de seguridad de la plataforma.
  </Card>

  <Card title="Resource Server" href="/es/data-holder/guides/build/resource-server">
    Construya e integre la API que Fiskil llama tras el consentimiento.
  </Card>

  <Card title="Métricas" href="/es/data-holder/guides/telemetry/metrics">
    Supervise TPS, invocaciones y rechazos por umbrales de tráfico.
  </Card>
</Cards>


---

# Configurar Microsoft (Entra ID) como Proveedor de SSO (/es/data-holder/guides/security/sso-microsoft)

Configure la autenticación de Inicio de Sesión Único para que su equipo acceda a la Consola de Fiskil usando su proveedor de identidad de Microsoft existente.



Microsoft (Entra ID) es un servicio de gestión de identidad y acceso basado en la nube que le permite administrar las identidades de usuario y el acceso a sus aplicaciones y recursos.

Requisitos Previos [#requisitos-previos]

<Check>
  Debe tener acceso a Microsoft Entra ID para configurar la autenticación de Inicio de Sesión Único con Microsoft.
</Check>

Configurar la autenticación de Inicio de Sesión Único [#configurar-la-autenticación-de-inicio-de-sesión-único]

<Steps>
  <Step title="Crear un nuevo registro de aplicación">
    Cree un nuevo [registro de aplicación de Microsoft Identity Platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) en Microsoft Entra ID
  </Step>

  <Step title="Configurar la aplicación">
    [Agregue una URI de redirección](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri):

    * tipo de plataforma: **Web**
    * URI de redirección: `https://enablement-prod.firebaseapp.com/__/auth/handler`
  </Step>

  <Step title="Configurar credenciales">
    [Cree un client secret](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret) en la nueva aplicación. Tome nota del valor del client secret (no del ID) cuando se cree por primera vez, ya que no se podrá recuperar posteriormente
  </Step>

  <Step title="Configurar el Inicio de Sesión de Fiskil">
    Use la Consola de Fiskil para [Habilitar SSO](/es/data-holder/guides/security/sso#how-to-enable-sso) proporcionando el Client ID, Client Secret y Directory (tenant) ID
  </Step>
</Steps>


---

# Inicio de Sesión SSO (/es/data-holder/guides/security/sso)

Habilite la autenticación de Inicio de Sesión Único para que su equipo acceda a la Consola de Fiskil usando su proveedor de identidad existente.



La autenticación de Inicio de Sesión Único (SSO) permite a sus usuarios iniciar sesión en la Consola de Fiskil usando las mismas credenciales que usan para otros servicios.

***

Proveedores Soportados [#proveedores-soportados]

Fiskil soporta identidad federada usando Microsoft Entra ID, con más proveedores de identidad próximamente, incluyendo:

<CardGroup cols={3}>
  <Card title="Google" icon="google">
    Cuentas de Google Workspace y Gmail
  </Card>

  <Card title="Microsoft" icon="microsoft">
    Microsoft Identity Platform y [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/)
  </Card>

  <Card title="Okta" icon="shield-check">
    Plataforma de gestión de identidad Okta
  </Card>

  <Card title="OIDC" icon="link">
    Cualquier IdP compatible con OIDC
  </Card>

  <Card title="Proveedor Personalizado" icon="gear">
    Contacte a soporte para proveedores adicionales
  </Card>
</CardGroup>

<Info>
  La autenticación con proveedores adicionales de OpenID Connect (OIDC) o Security Assertion Markup Language (SAML) 2.0 está disponible bajo solicitud a través del equipo de Fiskil.
</Info>

***

Cómo Habilitar SSO [#cómo-habilitar-sso]

SSO se puede configurar en la [Consola de Fiskil](https://console.fiskil.com/data-holder/settings/sso)

<Steps>
  <Step title="Configure su Proveedor de Identidad">
    <Card title="Configurar Microsoft (Entra ID) como Proveedor de SSO" href="/es/data-holder/guides/security/sso-microsoft" icon="microsoft">
      Cómo configurar la autenticación de Inicio de Sesión Único para que su equipo acceda a la Consola de Fiskil usando su proveedor de identidad de Microsoft existente.
    </Card>

    <Tip>
      Tome nota de su Client ID y Client Secret, los necesitará para los siguientes pasos.
    </Tip>
  </Step>

  <Step title="Activar SSO">
    Inicie sesión en la Consola de Fiskil y navegue al [menú de SSO](https://console.fiskil.com/data-holder/settings/sso). Seleccione su proveedor de identidad
    de la lista y complete el formulario. Deberá proporcionar su client ID, client secret y cualquier metadato específico del proveedor.

    <Warning>
      Verifique cuidadosamente sus parámetros de SSO. Una configuración incorrecta podría bloquear su acceso al portal. Si tiene problemas, contacte a [Soporte de Fiskil](https://fiskil.atlassian.net/servicedesk/customer/portal/6).
    </Warning>
  </Step>

  <Step title="Acceso de Usuarios">
    Una vez habilitado, los usuarios que intenten iniciar sesión son redirigidos a su proveedor de identidad. Después de una autenticación exitosa, regresan a la Consola de Fiskil con sesión iniciada con el rol asignado en **Configuración > Miembros**.
  </Step>
</Steps>

***


---

# Registros (/es/data-holder/guides/telemetry/logs)

Visualice y exporte los registros de solicitudes del Data Provider desde la Consola, o envíelos a sus herramientas de SIEM y observabilidad.



Los Registros de Solicitudes le dan visibilidad de cada llamada realizada a través de su Data Provider. Son esenciales para:

* Depurar problemas de integración
* Auditar acceso a datos consentidos
* Monitorear rendimiento y latencia
* Reenviar eventos a su stack SIEM u observabilidad

***

Estructura del Registro [#estructura-del-registro]

Fiskil exporta registros con la siguiente estructura. Note que esta estructura puede evolucionar en versiones futuras.

* `request_id`: Identificador de solicitud (string)
* `consent_id`: ID de consentimiento / ID de arreglo CDR (string)
* `fapi_interaction_id`: ID de interacción FAPI (string)
* `account_id`: Identificador canónico para la cuenta, si aplica (string)
* `customer_id`: Identificador para el cliente, si aplica (string)
* `app_name`: Nombre del cliente ADR solicitando datos (string)
* `level`: Nivel de severidad: "ERROR", "WARN", o "INFO" (string)
* `error_reason`: Descripción legible de la razón del error (string)
* `status_code`: Código de estado HTTP de la solicitud (number)
* `route_pattern`: Patrón de ruta de solicitud para endpoint de API accedido (string)
* `path`: Ruta de solicitud para endpoint de API accedido (string)
* `query`: Parámetros de consulta HTTP de la solicitud (string)
* `method`: Método HTTP de la solicitud (string)
* `latency_ms`: Tiempo tomado por la solicitud en milisegundos (number)
* `ip`: Dirección IPv4 del origen de la solicitud (string)
* `response_body_size`: Tamaño del cuerpo de respuesta HTTP en bytes (number)
* `timestamp`: Marca de tiempo ISO 8601 de la solicitud (string)
* `trace_id`: Identificador de rastreo interno de Fiskil (string)

***

Viendo Registros en la Consola [#viendo-registros-en-la-consola]

Acceda a registros de solicitudes en tiempo real directamente en la [Consola de Fiskil](https://console.fiskil.com/data-holder/logs) para depuración y monitoreo inmediato.

<Note>
  La interfaz de registros de solicitudes proporciona opciones de filtrado y visualización de entradas de registro para depuración y monitoreo inmediato.
</Note>

Filtrado y Búsqueda [#filtrado-y-búsqueda]

La Consola proporciona capacidades de filtrado poderosas para ayudarle a encontrar solicitudes específicas rápidamente:

* **ID de Cliente**: Filtre por identificadores de cliente específicos
* **ID de Consentimiento**: Vea registros para arreglos de consentimiento específicos
* **Ruta**: Filtre por patrones de endpoint de API
* **Rango de tiempo**: Acote a períodos de tiempo específicos
* **Estado HTTP**: Enfóquese en errores, éxitos, o códigos de respuesta específicos
* **Método HTTP**: Filtre por operaciones GET, POST, PUT, DELETE

Vista Detallada del Registro [#vista-detallada-del-registro]

Haga clic en cualquier entrada de registro individual para expandir y ver detalles completos incluyendo:

* Nombre de aplicación ADR y metadatos
* ID de rastreo interno para depuración
* IDs de cuenta asociados
* Temporización de solicitud y respuesta
* Contexto completo de error cuando aplique

<Tip>
  Use la vista expandida del registro para identificar rápidamente problemas de integración y rastrear flujos de solicitudes a través de su sistema.
</Tip>

***

Log Drains [#log-drains]

Los **Log Drains** son una característica poderosa que reenvía automáticamente los registros de solicitudes de su Data Provider a herramientas externas de observabilidad y SIEM. Esto le permite:

* Integrar registros en su infraestructura de monitoreo existente
* Configurar alertas y análisis automatizados
* Mantener almacenamiento centralizado de registros y políticas de retención
* Realizar análisis avanzados en todo su stack tecnológico

Cómo Funcionan los Log Drains [#cómo-funcionan-los-log-drains]

Configure [Log Drains](https://console.fiskil.com/data-holder/settings/log-drains) en la Consola para crear un flujo en tiempo real de eventos de registro desde su Data Provider a su destino elegido.

Destinos Soportados [#destinos-soportados]

<CardGroup cols={2}>
  <Card title="Azure Monitor" icon="microsoft">
    **Application Insights**: Transmita registros directamente a la plataforma de monitoreo de Azure con soporte completo de consultas KQL.
  </Card>

  <Card title="Elasticsearch" icon="magnifying-glass">
    **Data Streams**: Reenvíe registros a su clúster de Elasticsearch como flujos de datos estructurados.
  </Card>
</CardGroup>

<Info>
  ¿Necesita integración con una herramienta de observabilidad diferente? Contacte a [soporte](https://fiskil.atlassian.net/servicedesk/customer/portal/6/group/23/create/93) para discutir integraciones personalizadas.
</Info>

***

Configurando Log Drains [#configurando-log-drains]

Configuración de Azure Monitor [#configuración-de-azure-monitor]

Los registros se entregan a Azure a través de Application Insights. Pasos:

<Steps>
  <Step>
    Cree una nueva aplicación en Azure Monitor Application Insights
  </Step>

  <Step>
    Copie el "Connection String"
  </Step>

  <Step>
    Vaya a la configuración de Log Drain en la Consola de Fiskil
  </Step>

  <Step>
    Haga clic en la tarjeta de Azure
  </Step>

  <Step>
    Ingrese su connection string
  </Step>

  <Step>
    Guarde su log drain
  </Step>
</Steps>

Puede tomar unos minutos para que los registros aparezcan en Azure.
Los atributos del registro están en `customDimensions` del registro, y puede consultarlos con [KQL](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/log-query-overview).

***

Configuración de Elasticsearch [#configuración-de-elasticsearch]

Los registros se entregan a Elasticsearch como un data stream. La autenticación requiere una clave de API.

<Steps>
  <Step>
    Cree una API Key con privilegios:

    ```json
    PUT /_security/api_key
    {
        "name": "fiskil-ingest",
        "role_descriptors": {
            "logs_fiskil_holder_ingest_role": {
                "index": [
                    {
                        "names": ["logs-fiskil-holder"],
                        "privileges": ["write"]
                    }
                ]
            }
        }
    }
    ```
  </Step>

  <Step>
    Vaya a la configuración de Log Drain en la Consola
  </Step>

  <Step>
    Haga clic en la tarjeta de Elasticsearch
  </Step>

  <Step>
    Ingrese el endpoint de su clúster y la API Key codificada
  </Step>

  <Step>
    Guarde su log drain
  </Step>
</Steps>

Puede tomar unos minutos para que los registros comiencen a fluir a su clúster de Elasticsearch.


---

# Métricas (/es/data-holder/guides/telemetry/metrics)

Métricas operacionales completas rastreadas automáticamente para cumplimiento, monitoreo de rendimiento e insights de negocio.



Cada ambiente de Fiskil captura automáticamente un conjunto completo de métricas operacionales cubriendo rendimiento, disponibilidad, patrones de tráfico y actividad de autorización. Estas métricas son esenciales para cumplimiento con estándares de datos del consumidor y proporcionan insights valiosos para monitoreo y planificación de capacidad.

<Note>
  Las métricas se recolectan continuamente y se usan para reportes de cumplimiento. La visibilidad en la Consola y capacidades de exportación estarán disponibles próximamente.
</Note>

***

Métricas de Rendimiento y Disponibilidad [#métricas-de-rendimiento-y-disponibilidad]

<CardGroup cols={2}>
  <Card title="Monitoreo de Disponibilidad" icon="chart-line">
    Rastree el uptime del ambiente y la disponibilidad del servicio a lo largo de períodos de tiempo para asegurar cumplimiento de SLA.
  </Card>

  <Card title="Seguimiento de Rendimiento" icon="gauge-high">
    Monitoree tiempos de respuesta de API y tasas de éxito contra umbrales de rendimiento definidos.
  </Card>
</CardGroup>

| Métrica                          | Descripción                                                                  | Caso de Uso                                                          |
| -------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Disponibilidad**               | Porcentaje de tiempo que su ambiente está disponible para servir solicitudes | Monitoreo de SLA y reportes de cumplimiento                          |
| **Rendimiento**                  | Porcentaje de llamadas de API completadas dentro de umbrales de rendimiento  | Identificar degradación de rendimiento y necesidades de optimización |
| **Tiempo de Respuesta Promedio** | Tiempo de respuesta medio de su Resource Server en milisegundos              | Ajuste de rendimiento y planificación de capacidad                   |

***

Métricas de Tráfico y Uso [#métricas-de-tráfico-y-uso]

Entender patrones de tráfico y uso ayuda con la planificación de capacidad e identificación de tendencias en adopción de compartición de datos. [Fiskil Firewall](/es/data-holder/guides/security/firewall) también limita a los receptores de datos y bloquea tráfico abusivo para que su Resource Server vea una carga acotada.

| Métrica                | Descripción                                                                   | Insights Clave                                    |
| ---------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------- |
| **Invocaciones**       | Número total de llamadas de API recibidas, segmentadas por períodos de tiempo | Volumen de tráfico y patrones de uso              |
| **TPS Promedio**       | Promedio de transacciones por segundo a lo largo del tiempo                   | Características de carga en estado estable        |
| **TPS Pico**           | Máximo observado de transacciones por segundo                                 | Requisitos de capacidad pico                      |
| **Conteo de Sesiones** | Número de sesiones activas (eventos de provisión de token de acceso)          | Engagement de usuario y actividad de autorización |

***

Métricas de Autorización y Cumplimiento [#métricas-de-autorización-y-cumplimiento]

<Tabs items={["Actividad de Usuario", "Seguimiento de Errores", "Holders Secundarios"]}>
  <Tab value="Actividad de Usuario">
    Rastree el engagement de clientes y receptores con su plataforma de compartición de datos.

    | Métrica                           | Descripción                                                  |
    | --------------------------------- | ------------------------------------------------------------ |
    | **Conteo de Clientes**            | Número de clientes con autorizaciones activas                |
    | **Conteo de Receptores de Datos** | Número de aplicaciones receptoras con autorizaciones activas |
    | **Autorizaciones**                | Total de autorizaciones procesadas a lo largo del tiempo     |
  </Tab>

  <Tab value="Seguimiento de Errores">
    Monitoree tasas de error y solicitudes rechazadas para salud operacional.

    | Métrica      | Descripción                                               |
    | ------------ | --------------------------------------------------------- |
    | **Errores**  | Llamadas de API que resultaron en respuestas de error     |
    | **Rechazos** | Llamadas rechazadas debido a límites de umbral de tráfico |
  </Tab>

  <Tab value="Holders Secundarios">
    Para despliegues de responsabilidad compartida con data holders secundarios.

    | Métrica                           | Descripción                                   |
    | --------------------------------- | --------------------------------------------- |
    | **Errores de Holder Secundario**  | Errores recibidos de data holders secundarios |
    | **Rechazos de Holder Secundario** | Rechazos de data holders secundarios          |
  </Tab>
</Tabs>

***

Cómo las Métricas Apoyan sus Operaciones [#cómo-las-métricas-apoyan-sus-operaciones]

<AccordionGroup>
  <Accordion title="Cumplimiento y Reportes Regulatorios">
    Las métricas se rastrean automáticamente de acuerdo con estándares de datos del consumidor (CDR, FDX, etc.), asegurando que cumpla requisitos regulatorios sin esfuerzo manual.
  </Accordion>

  <Accordion title="Optimización de Rendimiento">
    Monitoree tiempos de respuesta, throughput y tasas de error para identificar oportunidades de optimización y asegurar que su Resource Server cumpla objetivos de rendimiento.
  </Accordion>

  <Accordion title="Planificación de Capacidad">
    Use patrones de tráfico, TPS pico y conteos de sesiones para planificar escalamiento de infraestructura y anticipar necesidades futuras de capacidad.
  </Accordion>

  <Accordion title="Preparación para Auditoría">
    Mantenga registros verificables de disponibilidad, actividad de autorización y métricas de rendimiento para auditorías de cumplimiento y revisiones regulatorias.
  </Accordion>
</AccordionGroup>

***

Disponibilidad Actual [#disponibilidad-actual]

<CardGroup cols={3}>
  <Card title="Recolección Automática" icon="check-circle">
    Todas las métricas se rastrean continuamente por Fiskil sin ninguna configuración requerida.
  </Card>

  <Card title="Listo para Cumplimiento" icon="shield-check">
    La recolección de métricas cumple con requisitos de estándares de datos del consumidor para monitoreo operacional.
  </Card>

  <Card title="Próximamente" icon="clock">
    La visibilidad en la Consola y capacidades de exportación a sistemas externos están en desarrollo.
  </Card>
</CardGroup>

<Info>
  Anunciaremos cuando las métricas estén disponibles para visualización en la Consola o exportación a sistemas de monitoreo externos.
</Info>

***

Documentación Relacionada [#documentación-relacionada]

<Cards>
  <Card title="Registros de Solicitudes" href="/es/data-holder/guides/telemetry/logs" icon={<DatabaseRestore />}>
    Vea registros detallados a nivel de solicitud y configure log drains a sistemas externos.
  </Card>

  <Card title="Lista de Verificación para Producción" href="/es/data-holder/guides/go-live" icon={<Building />}>
    Asegure que su ambiente esté listo para producción con nuestra lista de verificación completa.
  </Card>

  <Card title="Seguridad y Cumplimiento" href="/es/data-holder/guides/security/sso" icon={<Phone />}>
    Conozca las medidas de seguridad y certificaciones de cumplimiento de Fiskil.
  </Card>
</Cards>


---

# Pruebas de API (/es/data-holder/guides/product-portal/api-testing)

Pruebe su endpoint de Productos CDR directamente desde la Consola para verificar cómo se exponen los productos en staging y producción.



Pruebas de API [#pruebas-de-api]

<Info>
  Las Pruebas de API están actualmente en **Beta**. Esta función le permite verificar los datos de sus productos a través del endpoint de Productos CDR sin salir de la [Consola](https://console.fiskil.com/).
</Info>

La función de Prueba de API proporciona una forma integrada de verificar cómo se exponen sus productos a través de la API CDR en entornos de Staging y Producción. Úsela para confirmar que la configuración de su producto es correcta antes y después de publicar cambios.

<Card title="Abrir Portal de Productos" icon="arrow-up-right-from-square" href="https://console.fiskil.com/data-holder/products">
  Acceda a la función de Prueba de API en la Consola de Fiskil.
</Card>

***

Por qué usar Pruebas de API [#por-qué-usar-pruebas-de-api]

<CardGroup cols={2}>
  <Card title="Verificación instantánea" icon="bolt">
    Pruebe su endpoint de Productos directamente desde el [Portal de Productos](https://console.fiskil.com/data-holder/products) sin cambiar de herramientas.
  </Card>

  <Card title="Comparación de entornos" icon="code-compare">
    Compare respuestas de API entre Staging y Producción para verificar despliegues.
  </Card>

  <Card title="Depurar configuración" icon="bug">
    Identifique rápidamente problemas con datos de productos o configuración de exposición de API.
  </Card>

  <Card title="Validar antes de ir a producción" icon="shield-check">
    Confirme que sus productos aparecen correctamente en la API antes de publicar en Producción.
  </Card>
</CardGroup>

***

Accediendo a Prueba de API [#accediendo-a-prueba-de-api]

<Steps>
  <Step title="Navegue al Portal de Productos">
    En la [Consola de Fiskil](https://console.fiskil.com/), vaya al **[Portal de Productos](https://console.fiskil.com/data-holder/products)** desde la navegación principal.
  </Step>

  <Step title="Abrir Prueba de API">
    Haga clic en el botón **Probar API** en la esquina superior derecha de la página de Productos.
  </Step>

  <Step title="Ver el panel de Prueba de API">
    El panel de Prueba de API se abre, mostrando la configuración del endpoint de Productos CDR y vista previa de respuesta.
  </Step>
</Steps>

***

Usando el panel de Prueba de API [#usando-el-panel-de-prueba-de-api]

El panel de Prueba de API proporciona una interfaz completa para probar su endpoint de Productos.

Seleccionar entorno [#seleccionar-entorno]

Elija contra qué entorno probar:

| Entorno        | Caso de uso                                                             |
| -------------- | ----------------------------------------------------------------------- |
| **Staging**    | Verificar nuevos productos o cambios antes de publicar en Producción    |
| **Producción** | Confirmar que los datos de productos en vivo son correctos y accesibles |

<Tip>
  Siempre pruebe en Staging primero al hacer cambios. Una vez verificado, publique en Producción y pruebe nuevamente para confirmar el despliegue.
</Tip>

Configuración de solicitud [#configuración-de-solicitud]

El panel muestra los siguientes detalles de solicitud:

<ResponseField name="URL de Solicitud" type="string">
  La URL completa del endpoint de Productos CDR para su Data Provider. Se completa automáticamente basándose en la configuración de su ambiente y el entorno seleccionado.
</ResponseField>

<ResponseField name="Headers" type="object">
  Headers requeridos para la solicitud de API, incluyendo el header `x-v` que especifica la versión de API.

  <Expandable title="Headers comunes">
    <ResponseField name="x-v" type="integer">
      La versión de la API que se está llamando. Actualmente soporta versión `4`.
    </ResponseField>
  </Expandable>
</ResponseField>

Enviar una solicitud [#enviar-una-solicitud]

Haga clic en **Enviar Solicitud** para ejecutar la llamada de API. La respuesta aparece en el panel de abajo.

***

Entendiendo la respuesta [#entendiendo-la-respuesta]

Después de enviar una solicitud, el panel de Prueba de API muestra:

Estado de respuesta [#estado-de-respuesta]

Una insignia de estado indica el resultado:

| Estado               | Descripción                            |
| -------------------- | -------------------------------------- |
| **200 OK**           | Solicitud exitosa: productos devueltos |
| **400 Bad Request**  | Parámetros de solicitud inválidos      |
| **401 Unauthorized** | Autenticación fallida                  |
| **404 Not Found**    | Endpoint no encontrado                 |
| **500 Server Error** | Error interno del servidor             |

Cuerpo de respuesta [#cuerpo-de-respuesta]

El cuerpo de respuesta muestra el payload JSON devuelto por el endpoint de Productos. El endpoint Get Products devuelve una lista de productos con campos principales:

```json Respuesta Get Products
{
  "data": {
    "products": [
      {
        "productId": "home-loan-variable-001",
        "name": "Standard Variable Home Loan",
        "description": "Our standard variable rate home loan for owner occupiers with flexible repayment options.",
        "brand": "Example Bank",
        "brandName": "Example Bank",
        "productCategory": "RESIDENTIAL_MORTGAGES",
        "isTailored": false,
        "lastUpdated": "2025-01-15T09:30:00Z",
        "additionalInformation": {
          "overviewUri": "https://www.example.com.au/home-loans/variable",
          "termsUri": "https://www.example.com.au/home-loans/terms",
          "eligibilityUri": "https://www.example.com.au/home-loans/eligibility",
          "feesAndPricingUri": "https://www.example.com.au/home-loans/fees"
        }
      }
    ]
  },
  "links": {
    "self": "https://api.example.com.au/cds-au/v1/banking/products"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1
  }
}
```

Para obtener los detalles completos del producto incluyendo tasas, comisiones y características, llame al endpoint Get Product Detail:

```json Respuesta Get Product Detail
{
  "data": {
    "productId": "home-loan-variable-001",
    "name": "Standard Variable Home Loan",
    "description": "Our standard variable rate home loan for owner occupiers with flexible repayment options.",
    "brand": "Example Bank",
    "brandName": "Example Bank",
    "productCategory": "RESIDENTIAL_MORTGAGES",
    "isTailored": false,
    "lastUpdated": "2025-01-15T09:30:00Z",
    "additionalInformation": {
      "overviewUri": "https://www.example.com.au/home-loans/variable",
      "termsUri": "https://www.example.com.au/home-loans/terms",
      "eligibilityUri": "https://www.example.com.au/home-loans/eligibility",
      "feesAndPricingUri": "https://www.example.com.au/home-loans/fees"
    },
    "features": [
      {
        "featureType": "OFFSET",
        "additionalInfo": "100% offset account available"
      },
      {
        "featureType": "REDRAW",
        "additionalInfo": "Free redraw facility available"
      },
      {
        "featureType": "DIGITAL_BANKING",
        "additionalInfo": "Manage your loan via online and mobile banking"
      }
    ],
    "eligibility": [
      {
        "eligibilityType": "MIN_AGE",
        "additionalValue": "18"
      },
      {
        "eligibilityType": "RESIDENCY_STATUS",
        "additionalValue": "Australian citizen or permanent resident"
      }
    ],
    "fees": [
      {
        "name": "Application Fee",
        "feeType": "UPFRONT",
        "amount": "600.00",
        "currency": "AUD"
      },
      {
        "name": "Monthly Service Fee",
        "feeType": "PERIODIC",
        "amount": "10.00",
        "currency": "AUD",
        "additionalValue": "P1M"
      }
    ],
    "lendingRates": [
      {
        "lendingRateType": "VARIABLE",
        "rate": "0.0649",
        "comparisonRate": "0.0672",
        "calculationFrequency": "P1D",
        "applicationFrequency": "P1M",
        "interestPaymentDue": "IN_ARREARS",
        "repaymentType": "PRINCIPAL_AND_INTEREST",
        "loanPurpose": "OWNER_OCCUPIED",
        "additionalInfo": "Standard variable rate for owner occupied, principal and interest repayments"
      }
    ],
    "constraints": [
      {
        "constraintType": "MIN_LIMIT",
        "additionalValue": "50000.00"
      },
      {
        "constraintType": "MAX_LIMIT",
        "additionalValue": "5000000.00"
      }
    ]
  },
  "links": {
    "self": "https://api.example.com.au/cds-au/v1/banking/products/home-loan-variable-001"
  }
}
```

<Note>
  La respuesta sigue la [especificación de API de Producto Bancario CDR](https://consumerdatastandardsaustralia.github.io/standards/#get-products). Las tasas se expresan como decimales (por ejemplo, `0.0649` representa 6.49%). Consulte el estándar para definiciones completas de campos.
</Note>

***

Escenarios de prueba comunes [#escenarios-de-prueba-comunes]

Verificar un nuevo producto [#verificar-un-nuevo-producto]

Después de crear un producto en el Portal de Productos:

<Steps>
  <Step title="Desplegar a Staging">
    Despliegue su nuevo producto al entorno de Staging.
  </Step>

  <Step title="Abrir Prueba de API">
    Haga clic en **Probar API** y seleccione **Staging** como el entorno.
  </Step>

  <Step title="Enviar solicitud">
    Haga clic en **Enviar Solicitud** y verifique que su producto aparece en la respuesta.
  </Step>

  <Step title="Verificar campos del producto">
    Confirme que todos los campos están correctamente poblados, incluyendo:

    * `productId`
    * `name`
    * `description`
    * `productCategory`
    * `lastUpdated`
  </Step>
</Steps>

Comparar Staging y Producción [#comparar-staging-y-producción]

Para verificar que un despliegue fue exitoso:

<Steps>
  <Step title="Probar Staging">
    Seleccione el entorno **Staging** y envíe una solicitud. Note los productos y sus marcas de tiempo `lastUpdated`.
  </Step>

  <Step title="Probar Producción">
    Cambie al entorno **Producción** y envíe una solicitud.
  </Step>

  <Step title="Comparar respuestas">
    Verifique que los productos esperados aparecen en Producción con los datos correctos.
  </Step>
</Steps>

Depurar productos faltantes [#depurar-productos-faltantes]

Si un producto no aparece en la respuesta de API:

<AccordionGroup>
  <Accordion title="Producto no desplegado">
    Verifique el estado del producto en el [Portal de Productos](https://console.fiskil.com/data-holder/products). Los productos deben estar desplegados para aparecer en la API.

    * **NEEDS\_REVIEW**: El producto tiene cambios pendientes que necesitan aprobación
    * **DRAFT**: Producto aún no desplegado
    * **PUBLISHED**: El producto está en vivo
  </Accordion>

  <Accordion title="Entorno incorrecto seleccionado">
    Verifique que está probando el entorno correcto. Los productos desplegados a Staging no aparecerán en Producción hasta que se publiquen.
  </Accordion>

  <Accordion title="Producto archivado">
    Los productos archivados pueden no aparecer en el endpoint de lista de Productos. Verifique si el producto tiene una fecha `effectiveTo` expirada.
  </Accordion>

  <Accordion title="Errores de validación">
    Los productos con errores de validación no pueden ser desplegados. Regrese al editor de productos y resuelva cualquier error mostrado.
  </Accordion>
</AccordionGroup>

***

Mejores prácticas [#mejores-prácticas]

<CardGroup cols={2}>
  <Card title="Probar después de cada despliegue" icon="rotate">
    Siempre verifique la respuesta de API después de desplegar cambios para detectar problemas temprano.
  </Card>

  <Card title="Comparar entornos regularmente" icon="code-compare">
    Compare Staging y Producción regularmente para asegurar que estén sincronizados como se espera.
  </Card>

  <Card title="Verificar marcas de tiempo" icon="clock">
    Use el campo `lastUpdated` para confirmar que está viendo la última versión de sus productos.
  </Card>

  <Card title="Documentar problemas" icon="file-lines">
    Si encuentra respuestas inesperadas, anote los detalles antes de contactar a soporte.
  </Card>
</CardGroup>

***

Limitaciones [#limitaciones]

<Warning>
  Las Pruebas de API están actualmente en Beta y tienen las siguientes limitaciones:
</Warning>

* **Solo endpoint de Productos**: Actualmente soporta probar el endpoint Get Products. Endpoints adicionales pueden agregarse en futuras versiones.
* **Solo lectura**: No puede modificar datos de productos a través del panel de Prueba de API.
* **Sin pruebas de autenticación**: La prueba usa autenticación interna. No prueba flujos de autenticación de clientes externos.

***

Recursos relacionados [#recursos-relacionados]

<CardGroup cols={2}>
  <Card title="Creando productos" icon="plus" href="/es/data-holder/guides/product-portal/creating-products">
    Aprenda cómo crear y gestionar productos en el Portal de Productos.
  </Card>

  <Card title="Referencia de API de Plataforma" icon="list" href="/es/data-holder/platform-api/introduction">
    Gestione productos programáticamente a través de la API de Plataforma.
  </Card>

  <Card title="Pruebas con Postman" icon="rocket" href="/es/data-holder/guides/testing/postman">
    Use Postman para escenarios de prueba de API más avanzados.
  </Card>

  <Card title="Requisitos de integración CDR" icon="book" href="/data-holder/api-reference/cdr/integration-requirements">
    Entienda los requisitos técnicos para la integración de API CDR.
  </Card>
</CardGroup>


---

# Creación y Gestión de Productos (/es/data-holder/guides/product-portal/creating-products)

Aprenda cómo crear, editar, aprobar y publicar productos en el Portal de Productos.



Esta guía describe el ciclo completo de gestión de productos en el Portal de Productos, desde la creación inicial hasta la publicación de cambios en el entorno productivo.

Antes de comenzar [#antes-de-comenzar]

<Check>
  Asegúrese de tener acceso a la [Consola de Fiskil](https://console.fiskil.com/) con los permisos apropiados para el [Portal de Productos](https://console.fiskil.com/data-holder/products).
</Check>

<Info>
  Todos los cambios de productos siguen un flujo de trabajo controlado: crear o editar en **Staging**, revisar y aprobar, luego publicar en **Producción**.
</Info>

***

Resumen del ciclo de vida del producto [#resumen-del-ciclo-de-vida-del-producto]

Cada producto en el Portal de Productos sigue un ciclo de vida consistente:

<Steps>
  <Step title="Crear o editar">
    Agregue un nuevo producto o realice cambios a uno existente. Todos los cambios comienzan en modo borrador.
  </Step>

  <Step title="Revisar y validar">
    Revise sus cambios en la [Consola](https://console.fiskil.com/). Los errores de validación se muestran en línea antes de poder proceder.
  </Step>

  <Step title="Desplegar a Staging">
    Despliegue su producto al entorno de Staging para pruebas. Puede verificar los datos del producto a través de la API.
  </Step>

  <Step title="Aprobar y publicar">
    Una vez validado, apruebe los cambios y publique en Producción. Esto hace que el producto esté disponible para los receptores de datos.
  </Step>
</Steps>

***

Creando un nuevo producto [#creando-un-nuevo-producto]

<Steps>
  <Step title="Navegue al Portal de Productos">
    En la [Consola de Fiskil](https://console.fiskil.com/), vaya al **[Portal de Productos](https://console.fiskil.com/data-holder/products)** desde la navegación principal.
  </Step>

  <Step title="Haga clic en Agregar Nuevo Producto">
    Seleccione **+ Agregar Nuevo Producto** para abrir el formulario de producto.
  </Step>

  <Step title="Complete los campos requeridos">
    Complete los detalles obligatorios del producto:

    | Campo                      | Descripción                                              |
    | -------------------------- | -------------------------------------------------------- |
    | **ID del Producto**        | Identificador único (por ejemplo, `savings-account-001`) |
    | **Nombre del producto**    | Nombre de visualización mostrado a los clientes          |
    | **Categoría del producto** | Categoría de la especificación regulada                  |
    | **Descripción**            | Descripción pública corta del producto                   |

    <Note>
      Vea la [Referencia de API de Plataforma](/es/data-holder/platform-api/introduction) para una lista completa de todos los campos disponibles.
    </Note>
  </Step>

  <Step title="Agregue detalles opcionales">
    Expanda secciones adicionales para configurar:

    * **Características**: capacidades como banca digital, cuentas offset
    * **Elegibilidad**: quién puede solicitar el producto
    * **Comisiones**: cargos y descuentos opcionales
    * **Tasas**: tasas de depósito o préstamo con niveles
    * **Paquetes**: agrupe productos juntos
  </Step>

  <Step title="Guardar borrador">
    Haga clic en **Guardar** para almacenar su producto como borrador. Puede continuar editando antes de desplegar.
  </Step>
</Steps>

***

Editando un producto existente [#editando-un-producto-existente]

<Steps>
  <Step title="Encuentre el producto">
    Use las opciones de búsqueda o filtro en el [Portal de Productos](https://console.fiskil.com/data-holder/products) para localizar el producto que desea editar.
  </Step>

  <Step title="Abra el producto">
    Haga clic en la fila del producto para abrir la vista de detalle del producto.
  </Step>

  <Step title="Haga clic en Editar">
    Seleccione **Editar** para habilitar el modo de edición. Esto crea una nueva versión borrador del producto.

    <Warning>
      Los cambios no son visibles para los receptores de datos hasta que los despliegue y publique.
    </Warning>
  </Step>

  <Step title="Realice sus cambios">
    Actualice cualquier campo según sea necesario. El formulario valida sus cambios en tiempo real.
  </Step>

  <Step title="Guardar y revisar">
    Guarde sus cambios y revise el diff para confirmar qué ha cambiado.
  </Step>
</Steps>

***

Desplegando a Staging [#desplegando-a-staging]

Antes de publicar en producción, debe validar sus cambios en Staging.

<Steps>
  <Step title="Revise su borrador">
    Abra el producto y revise los cambios pendientes. La Consola muestra una comparación detallada de los cambios que serán desplegados.
  </Step>

  <Step title="Desplegar a Staging">
    Haga clic en **Desplegar a Staging**. Esto envía los datos de su producto al entorno de Staging.
  </Step>

  <Step title="Verificar vía API">
    Use la función **Probar API** integrada para verificar que su producto aparece correctamente:

    1. Haga clic en **Probar API** en la esquina superior derecha del [Portal de Productos](https://console.fiskil.com/data-holder/products)
    2. Seleccione **Staging** como el entorno
    3. Haga clic en **Enviar Solicitud** para ver sus productos

    <Tip>
      La función de [Pruebas de API](/es/data-holder/guides/product-portal/api-testing) le permite verificar productos sin salir de la [Consola](https://console.fiskil.com/). Para pruebas más avanzadas, use [Postman](/es/data-holder/guides/testing/postman).
    </Tip>
  </Step>

  <Step title="Corregir cualquier problema">
    Si encuentra problemas, regrese a la [Consola](https://console.fiskil.com/), edite el producto y vuelva a desplegar a Staging.
  </Step>
</Steps>

***

Aprobando y publicando a Producción [#aprobando-y-publicando-a-producción]

Una vez que su producto está validado en Staging, puede publicarlo en Producción.

<Steps>
  <Step title="Solicitar aprobación">
    Si su organización usa flujos de trabajo de aprobación, envíe el producto para revisión.
  </Step>

  <Step title="Aprobar cambios">
    Un aprobador autorizado revisa y aprueba los cambios.

    <Note>
      Los flujos de trabajo de aprobación son configurables. Contacte al equipo de Fiskil para configurar reglas de aprobación para su organización.
    </Note>
  </Step>

  <Step title="Publicar en Producción">
    Haga clic en **Publicar en Producción**. El producto ahora está en vivo y accesible para los receptores de datos.

    <Check>
      Su producto ahora es visible en el endpoint público de API de Productos.
    </Check>
  </Step>
</Steps>

***

Programando actualizaciones de productos [#programando-actualizaciones-de-productos]

El Portal de Productos soporta programar cambios para que entren en vigencia en una fecha y hora futura.

<Steps>
  <Step title="Prepare sus cambios">
    Edite el producto y guarde sus cambios como borrador.
  </Step>

  <Step title="Establecer fecha efectiva">
    Al desplegar, seleccione **Programar** y elija la fecha y hora para que los cambios tomen efecto.
  </Step>

  <Step title="Confirmar programación">
    La [Consola](https://console.fiskil.com/) muestra el despliegue programado. Puede cancelar o modificar la programación antes de que se ejecute.
  </Step>
</Steps>

<Info>
  Los cambios programados se aplican automáticamente en el momento especificado. No se requiere acción manual una vez programado.
</Info>

***

Archivando productos [#archivando-productos]

Cuando un producto se descontinúa o ya no se ofrece:

<Steps>
  <Step title="Abra el producto">
    Navegue al producto que desea archivar.
  </Step>

  <Step title="Establecer fechas efectivas">
    Actualice la fecha **Efectivo Hasta** para indicar cuándo el producto ya no está disponible para nuevas solicitudes.
  </Step>

  <Step title="Archivar el producto">
    Seleccione **Archivar** para eliminar el producto de los listados activos. Los productos archivados permanecen en el sistema para referencia histórica.

    <Warning>
      Los productos archivados pueden seguir apareciendo en las respuestas de API si están vinculados a cuentas de clientes existentes.
    </Warning>
  </Step>
</Steps>

***

Mejores prácticas [#mejores-prácticas]

<CardGroup cols={2}>
  <Card title="Probar en Staging primero" icon="flask">
    Siempre despliegue y verifique productos en Staging antes de publicar en Producción.
  </Card>

  <Card title="Usar IDs descriptivos" icon="tag">
    Elija IDs de producto que sean significativos y consistentes en toda su organización.
  </Card>

  <Card title="Documentar cambios" icon="file-lines">
    Agregue notas al editar productos para mantener un rastro de auditoría claro.
  </Card>

  <Card title="Revisar antes de publicar" icon="magnifying-glass">
    Use la vista de diff para confirmar los cambios antes de publicar en Producción.
  </Card>
</CardGroup>

***

Reglas de validación [#reglas-de-validación]

El Portal de Productos valida sus datos contra la especificación regulada. Los errores de validación comunes incluyen:

| Error                                       | Causa                           | Solución                                           |
| ------------------------------------------- | ------------------------------- | -------------------------------------------------- |
| **Campo requerido faltante**                | Un campo obligatorio está vacío | Complete todos los campos requeridos               |
| **Valor no válido para el campo enumerado** | Valor no en lista permitida     | Seleccione de las opciones del desplegable         |
| **ID de producto duplicado**                | El ID de producto ya existe     | Elija un ID de producto único                      |
| **Formato de URI inválido**                 | URL malformada                  | Asegúrese de que las URLs comiencen con `https://` |
| **Campo condicional requerido**             | Falta un campo dependiente      | Vea las reglas condicionales del campo             |

<Tip>
  Consulte la [Referencia de API de Plataforma](/es/data-holder/platform-api/introduction) para reglas de validación detalladas para cada campo.
</Tip>

***

Recursos relacionados [#recursos-relacionados]

<CardGroup cols={2}>
  <Card title="Referencia de API de Plataforma" icon="list" href="/es/data-holder/platform-api/introduction">
    Gestione productos programáticamente a través de la API de Plataforma.
  </Card>

  <Card title="Pruebas de API" icon="flask" href="/es/data-holder/guides/product-portal/api-testing">
    Verifique sus productos a través de la API CDR.
  </Card>

  <Card title="Pruebas con Postman" icon="rocket" href="/es/data-holder/guides/testing/postman">
    Verifique los datos de sus productos usando colecciones de Postman.
  </Card>
</CardGroup>


---

# Qué es el Portal de Productos (/es/data-holder/guides/product-portal/what-is-product-portal)

Descubra cómo el Portal de Productos le permite gestionar, aprobar y publicar información de productos en cumplimiento con los estándares aplicables.



Portal de Productos [#portal-de-productos]

[Portal de Productos](https://console.fiskil.com/data-holder/products) es el sistema de gestión de productos de Fiskil para crear y publicar productos. Soporta publicación a través de APIs reguladas (como el Consumer Data Right). Proporciona un lugar central para que su equipo mantenga información de productos, realice cambios de forma segura y asegure que las actualizaciones sean revisadas y desplegadas correctamente.

<Card title="Abrir Portal de Productos" icon="arrow-up-right-from-square" href="https://console.fiskil.com/data-holder/products">
  Acceda al Portal de Productos en la Consola de Fiskil para gestionar sus productos.
</Card>

***

Qué puede hacer con el Portal de Productos [#qué-puede-hacer-con-el-portal-de-productos]

<CardGroup cols={2}>
  <Card title="Crear y mantener productos" icon="plus">
    Construya su catálogo de productos en un repositorio único y estructurado con validación completa de campos.
  </Card>

  <Card title="Editar productos de forma segura" icon="pen-to-square">
    Realice cambios usando un flujo de trabajo integrado con borradores, aprobaciones y registro de auditoría.
  </Card>

  <Card title="Programar actualizaciones" icon="calendar">
    Configure cambios de productos para que entren en vigencia automáticamente en una fecha y hora futura.
  </Card>

  <Card title="Probar antes de publicar" icon="flask" href="/es/data-holder/guides/product-portal/api-testing">
    Despliegue cambios a Staging y verifique a través de la API antes de publicar en Producción.
  </Card>
</CardGroup>

***

Cuándo usar el Portal de Productos [#cuándo-usar-el-portal-de-productos]

El Portal de Productos está diseñado para organizaciones que necesitan:

* Gestione la información de productos de manera controlada, digital y escalable.
* Compartir datos de productos a través de estándares regulados (por ejemplo, datos de referencia de productos CDR)
* Asegurar que los cambios sean revisados y aprobados antes de publicar
* Soportar flujos de trabajo de cumplimiento, aprobaciones de cambios y auditoría

***

Entornos de productos [#entornos-de-productos]

El Portal de Productos soporta un flujo de trabajo de entorno estándar para asegurar que los cambios sean validados antes de entrar en vigencia.

<Steps>
  <Step title="Staging (pruebas)">
    Usado para validar nuevos productos y cambios antes de publicar. Despliegue aquí primero para probar la salida de la API.
  </Step>

  <Step title="Producción (en vivo)">
    Donde los productos y cambios aprobados se publican para los receptores de datos. Solo despliegue después de la validación en Staging.
  </Step>
</Steps>

<Tip>
  Si necesita entornos adicionales (por ejemplo, staging o sandbox), [contacte al equipo de Fiskil](https://www.fiskil.com/contact).
</Tip>

***

Próximos pasos [#próximos-pasos]

<CardGroup cols={2}>
  <Card title="Crear su primer producto" icon="rocket" href="/es/data-holder/guides/product-portal/creating-products">
    Aprenda cómo crear, editar y publicar productos paso a paso.
  </Card>

  <Card title="Referencia de API de Plataforma" icon="list" href="/es/data-holder/platform-api/introduction">
    Gestione productos programáticamente a través de la API de Plataforma.
  </Card>

  <Card title="Probar su API" icon="flask" href="/es/data-holder/guides/product-portal/api-testing">
    Verifique cómo sus productos se exponen a través de la API CDR.
  </Card>
</CardGroup>


---

# Herramientas de Cumplimiento (/es/data-holder/guides/testing/compliance-tools)

Soporte para validar ambientes regulados del Data Provider contra requisitos de conformidad.



Si su ambiente de Data Provider está operando bajo un **perfil de cumplimiento** (por ejemplo, CDR, FDX, open banking), puede requerirse validación adicional antes de ir a producción.

La validación de cumplimiento asegura que:

* Todos los endpoints requeridos están implementados correctamente
* Las respuestas se alinean con esquemas y headers mandatorios
* Los flujos de consentimiento cumplen las expectativas regulatorias
* Las obligaciones de métricas y reportes pueden ser demostradas

***

Cómo Ayuda Fiskil [#cómo-ayuda-fiskil]

Cuando aplican requisitos de cumplimiento, Fiskil puede apoyarle en:

* **Validar endpoints** contra requisitos de pruebas de conformidad regulatoria
* **Prepararse para registro** (por ejemplo, registros de Receptores de Datos Acreditados)
* **Trabajar con integradores u operadores de mercado** para confirmar compatibilidad
* **Solucionar errores** descubiertos durante la validación de cumplimiento

***

Solicitando Soporte [#solicitando-soporte]

Las herramientas y procesos de validación de cumplimiento varían según el marco.
Por favor [contacte al equipo de Fiskil](https://fiskil.com/contact) para:

* Discutir el marco de cumplimiento bajo el cual está operando
* Entender qué validación y pruebas de conformidad son requeridas
* Acceder a herramientas de prueba adicionales donde estén disponibles
* Coordinarse con Fiskil para completar la certificación o registro

<Note>
  Si su ambiente no usa un perfil de cumplimiento, no necesita ejecutar validación regulatoria.
  Las pruebas funcionales con [Postman](/es/data-holder/guides/testing/postman) y [Registros de Solicitudes](/es/data-holder/guides/telemetry/logs) son suficientes.
</Note>

***

Áreas de Cobertura de Ejemplo [#áreas-de-cobertura-de-ejemplo]

Durante la validación de cumplimiento, puede necesitar demostrar:

* Endpoints de descubrimiento de clientes y cuentas
* Comportamiento del ciclo de vida del consentimiento (crear, revisar, revocar)
* Códigos de error y manejo de errores
* Umbrales de rendimiento y disponibilidad
* Métricas de reportes

***

***

Relacionado [#relacionado]

* [Métricas](/es/data-holder/guides/telemetry/metrics)
* [Lista de Verificación para Producción](/es/data-holder/guides/go-live)


---

# Visión General (/es/data-holder/guides/testing)

Cómo probar y validar su integración de Data Provider de Fiskil antes de ir a producción.



Antes de habilitar el entorno productivo, cada integración debe ser sometida a pruebas y validación. Fiskil ofrece herramientas para comprobar la correcta operación del Resource Server y la conformidad con el marco regulatorio aplicable, cuando corresponda.

***

Qué Puede Probar [#qué-puede-probar]

* **Flujos de autorización**: confirme que los usuarios pueden otorgar y revocar consentimiento exitosamente.
* **Validación de tokens**: verifique que su Resource Server aplica firmas JWT.
* **Respuestas de API**: valide que sus endpoints devuelven los datos correctos, formatos de error y paginación.
* **Rendimiento** — medir latencia y capacidad de procesamiento para validar los SLA base.
* **Cumplimiento (opcional)**: ejecute contra suites de prueba formales si está construyendo bajo CDR, FDX o marcos similares.

***

Herramientas Principales [#herramientas-principales]

Colección Postman [#colección-postman]

Realice una prueba de flujo end-to-end mediante la colección oficial de Postman proporcionada por Fiskil:

* Crear consentimientos
* Obtener tokens
* Llamar a sus endpoints del Resource Server
* Inspeccionar respuestas

Receptor de Datos Simulado [#receptor-de-datos-simulado]

Fiskil mantiene un Receptor de Datos CDR Simulado que puede usar para simular flujos de Consentimiento CDR:

* Crear consentimientos
* Navegar datos del consumidor
* Revocar consentimientos

***

Registros de Solicitudes [#registros-de-solicitudes]

Cada llamada de API se registra en [Registros de Solicitudes](/es/data-holder/guides/telemetry/logs).

* Valide payloads, alcances y códigos de estado.
* Depure errores rastreando solicitudes fallidas.
* Confirme que el tráfico fluye solo dentro del consentimiento otorgado.

***

Métricas [#métricas]

Cada ambiente rastrea métricas de rendimiento y disponibilidad.

* Verifique la latencia y la capacidad de procesamiento bajo carga.
* Compruebe tasas de error base antes de ir a producción.

Ver: [Métricas](/es/data-holder/guides/telemetry/metrics)

***

Herramientas de Cumplimiento [#herramientas-de-cumplimiento]

Si su ambiente usa un **perfil de cumplimiento** (por ejemplo, CDR, FDX), Fiskil proporciona acceso a herramientas de validación de cumplimiento.

* Ejecute verificaciones automatizadas contra endpoints y alcances requeridos.
* Genere reportes para reguladores o auditoría interna.

<Note>
  Para entornos regulados, pueden requerirse herramientas de prueba adicionales.
  Por favor [contacte al equipo de Fiskil](https://fiskil.com/contact) para habilitar soporte de pruebas de cumplimiento para su ambiente.
</Note>

Ver: [Herramientas de Cumplimiento](/es/data-holder/guides/testing/compliance-tools)

***

Entornos [#entornos]

Siempre pruebe exhaustivamente en **staging** antes de promover a **producción**:

* Staging permite receptores simulados y controles de cambio relajados.
* Producción debe permanecer estable y lista para auditoría.

***

Relacionado [#relacionado]

* [Usando Postman](/es/data-holder/guides/testing/postman)
* [Registros de Solicitudes](/es/data-holder/guides/telemetry/logs)
* [Métricas](/es/data-holder/guides/telemetry/metrics)
* [Herramientas de Cumplimiento](/es/data-holder/guides/testing/compliance-tools)


---

# Pruebas en Postman (/es/data-holder/guides/testing/postman)

Valide su integración de extremo a extremo utilizando nuestra colección de Postman, sus usuarios de prueba y los registros de solicitudes.



Esta guía explica cómo probar su integración de Data Provider de extremo a extremo utilizando Postman. Iniciará un flujo de consentimiento gestionado por Fiskil, obtendrá los tokens correspondientes y realizará llamadas a los endpoints de su Resource Server. También aprenderá a verificar los resultados en los registros de solicitudes y dónde encontrar herramientas adicionales para perfiles regulados (por ejemplo, CDR).

***

Visión General [#visión-general]

* **Herramienta principal**: Colección Postman proporcionada por Fiskil
* **Qué probará**: consentimiento → token → llamadas al Resource Server
* **Qué proporciona usted**: usuarios simulados, cuentas y datos de ejemplo en sus propios sistemas
* **Validación**: utilice la Consola → Registros de solicitudes para confirmar el éxito y analizar posibles errores.

***

Prerrequisitos [#prerrequisitos]

* Un ambiente de **staging** configurado en la Consola
* Su **Resource Server** en vivo en una URL HTTPS pública
* Endpoints requeridos implementados:
  * `GET /v1/auth/customer/search`
  * `GET /v1/auth/customer/{customerId}/accounts`
  * `GET /v1/auth/customer/{customerId}`
  * Al menos un endpoint de datos (por ejemplo, `GET /v1/customer/{customerId}/accounts/{accountId}/balances`)
* Acceso a los endpoints de **Autorización** y **Token**, y **URL JWKS**
  *(Todos disponibles en Consola → **Configuración → Dominios**.)*

> Recomendamos configurar varios **usuarios simulados** y **cuentas simuladas** en sus sistemas para probar una variedad de escenarios (cuentas individuales vs conjuntas, diferentes tipos de cuenta, casos de pocos/ningún dato, etc.).

***

Obtener la Colección Postman [#obtener-la-colección-postman]

1. Descargue la **colección Postman** y **entorno** de Fiskil (enlace proporcionado en la Consola o por su contacto de Fiskil).
2. Importe ambos en Postman.
3. Abra el entorno y complete las variables (ver siguiente sección).

***

Configurar el Entorno Postman [#configurar-el-entorno-postman]

Configure las siguientes variables en su **entorno** de Postman:

* `base_url`: URL base de su entorno staging del Proveedor de Datos
* `jwks_url`: Como se muestra en Consola → **Configuración → Dominios**
* `client_id`: Proporcionado durante la incorporación (o creado en la Consola)
* `client_secret`: Proporcionado durante la incorporación (o creado en la Consola)
* `scopes`: Lista delimitada por espacios (por ejemplo, `accounts.read balances.read`)

> Todos los valores de dominio y endpoint están disponibles en la Consola bajo **Configuración → Dominios** o **Configuración → Resource Server**.

***

Autorizar y Obtener un Token (Postman) [#autorizar-y-obtener-un-token-postman]

Use el flujo OAuth 2.0 integrado de Postman:

1. En la colección, abra **Authorization** en una solicitud que usa OAuth 2.0.
2. Configure:
   * **Auth URL**: `{{base_url}}/connect/authorize`
   * **Access Token URL**: `{{base_url}}/connect/token`
   * **Client ID**: `{{client_id}}`
   * **Client Secret**: `{{client_secret}}` (si aplica)
   * **Scopes**: `{{scopes}}`
   * **Grant Type**: Authorization Code (PKCE si es requerido)
3. Haga clic en **Get New Access Token**.
4. Complete la **pantalla de consentimiento alojada** (Fiskil) como el usuario de prueba.
5. Postman intercambiará el código y almacenará el **token de acceso**.
6. Haga clic en **Use Token** para adjuntarlo a solicitudes posteriores.

***

Llamar a sus Endpoints del Resource Server [#llamar-a-sus-endpoints-del-resource-server]

Con el token configurado en Postman, puede obtener algunos datos:

* `GET {{base_url}}/api/v1/accounts/{{account_id}}/balances`
* Espere datos de balance dentro del alcance del consentimiento.

> Asegúrese de que su Resource Server valide el JWT (firma, `exp`, `iss/sub`, `aud`, `jti`).

***

Usar Registros de Solicitudes para Validación [#usar-registros-de-solicitudes-para-validación]

Abra **Consola → Registros de Solicitudes** para verificar:

* **Llamadas exitosas** (200s) a sus endpoints después del consentimiento
* **Alcances** adjuntos al token y usados en cada solicitud
* **Respuestas de error** (401/403) cuando faltan alcances o los tokens son inválidos/expirados
* **Inspección de payload** para solución de problemas

***

Creando Usuarios y Datos Simulados [#creando-usuarios-y-datos-simulados]

Usted posee los datos de usuario y cuenta expuestos por su Resource Server. Para pruebas robustas:

* Cree **múltiples usuarios de prueba** que reflejen personas realistas:
  * Usuario individual con una cuenta
  * Usuario con múltiples cuentas de diferentes tipos
  * Cuentas conjuntas/organizacionales (si se soportan)
* Genere **casos extremos**:
  * Conjuntos de datos vacíos (sin transacciones aún)
  * Alcances restringidos (por ejemplo, solo balances)
  * Casos de paginación grande
* Mantenga un mapeo de usuarios de prueba → cuentas → resultados esperados para acelerar la revisión de pruebas.

***

Errores Comunes [#errores-comunes]

* **401 Unauthorized**: Token faltante o inválido. Valide firma y tiempo de vida del token.
* **400/422**: Errores de validación de solicitud (parámetros faltantes, IDs malformados).
* **429**: Límites de tasa (si están configurados).
* **5xx**: Errores upstream o del Resource Server.

***

Ejecutando la Colección como Suite [#ejecutando-la-colección-como-suite]

* Use un **Collection Runner** con un archivo de datos (CSV/JSON) de usuarios/cuentas de prueba.
* Agregue **scripts pre-solicitud** para inyectar IDs de cuenta de respuestas anteriores.
* Agregue **pruebas** en Postman (por ejemplo, `pm.expect(response.code).to.eql(200)`) para verificar códigos de estado y estructuras.

***

Herramientas Adicionales para Perfiles Regulados [#herramientas-adicionales-para-perfiles-regulados]

Si está implementando un **Perfil de Cumplimiento** (por ejemplo, **CDR**), hay disponibles herramientas de prueba y listas de verificación adicionales.

* Ver: [Herramientas de Cumplimiento y Certificación](/es/data-holder/guides/testing/compliance-tools)

> Estas herramientas complementan la colección Postman con validación específica del perfil, reglas de payload y flujos de trabajo de certificación.

***

Próximos Pasos [#próximos-pasos]

* Revise **Autenticación** para confirmar validación JWT y uso de JWKS.
* Confirme el ciclo de vida del **Consentimiento** y pantallas alojadas.
* Construya endpoints y alcances adicionales del **Resource Server**.
* Monitoree **Registros de Solicitudes** durante el desarrollo continuo y antes de ir a producción.


---

# Reportes Regulatorios (/es/data-holder/guides/testing/regulatory-reporting)

Cómo preparar el reporte semestral de titular de datos CDR usando Fiskil Console Analytics.



Los Titulares de Datos CDR deben enviar un reporte de cumplimiento a la ACCC cada seis meses a través del **Portal CDR** en [portal.cdr.gov.au](https://portal.cdr.gov.au/). Esta guía explica cómo usar la Consola de Fiskil para encontrar las cifras que necesita y proporciona contexto sobre lo que pregunta cada pregunta del formulario de reporte.

<Note>
  Esta guía es información general únicamente y no constituye asesoría legal. Confirme siempre su posición de reporte con las Reglas CDR y la orientación de la ACCC más recientes.
</Note>

***

Periodos de reporte y fechas límite [#periodos-de-reporte-y-fechas-límite]

Los periodos de reporte son:

* **1 de enero al 30 de junio**
* **1 de julio al 31 de diciembre**

Los reportes deben enviarse **dentro de los 30 días posteriores al final** de cada periodo de reporte. En la práctica, esto suele ser:

* Periodo que finaliza el **30 de junio** → vence el **30 de julio**
* Periodo que finaliza el **31 de diciembre** → vence el **30 de enero**

***

Uso de la pestaña Analytics [#uso-de-la-pestaña-analytics]

La mayoría de los datos que necesita para el reporte regulatorio están disponibles directamente en la Consola de Fiskil, en la pestaña **Analytics**. Siga estos pasos en cada periodo de reporte.

Paso 1 — Abrir Analytics [#paso-1--abrir-analytics]

1. Abra la [Consola de Fiskil](https://console.fiskil.com) y seleccione su **espacio de trabajo de Data Provider** desde el selector superior izquierdo.
2. Haga clic en **Analytics** en la barra de navegación superior.
3. Verá mosaicos para:
   * **Solicitudes de Datos de Consumidor** (Consumer Data Requests)
   * **Solicitudes de Datos de Producto** (Product Data Requests)
   * **Rechazos** (Total, 403, 404, 422)

Paso 2 — Seleccionar el entorno correcto [#paso-2--seleccionar-el-entorno-correcto]

Use el **selector de entorno** en la parte superior derecha para elegir **Producción**.

El entorno de pruebas (Staging) se utiliza para testing y no debe usarse para envíos regulatorios.

Paso 3 — Establecer su periodo de reporte [#paso-3--establecer-su-periodo-de-reporte]

En la sección **Periodo** a la izquierda, establezca el rango de fechas que corresponde a su periodo de reporte:

| Periodo de Reporte           | Rango de Fechas a Ingresar |
| ---------------------------- | -------------------------- |
| 1 de enero – 30 de junio     | 01/01/AAAA → 01/07/AAAA    |
| 1 de julio – 31 de diciembre | 01/07/AAAA → 01/01/AAAA    |

> **Nota:** El selector de rango de fechas **excluye la fecha final**. Para capturar los datos hasta el 31 de diciembre inclusive, ingrese el 1 de enero del año siguiente como fecha final. La misma lógica aplica para el periodo de junio.

Los mosaicos se actualizarán automáticamente una vez que establezca el rango de fechas.

***

Qué Reportar — Pregunta por Pregunta [#qué-reportar--pregunta-por-pregunta]

Las tablas a continuación asignan cada pregunta del formulario de reporte al lugar donde puede encontrar la respuesta en la Consola de Fiskil, y explican qué pregunta cada una.

Quejas (Preguntas 1–7) [#quejas-preguntas-17]

Los datos de quejas se gestionan a través de su propio sistema interno de gestión de quejas. Fiskil no captura la recepción ni la resolución de quejas; deberá recopilar estas cifras de forma independiente.

| Pregunta                                                  | Qué pregunta                                                                                                                                                                 | Dónde encontrarlo                                                                                                            |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Q1 — Quejas sobre datos de producto                       | Total de quejas CDR recibidas relacionadas con datos de producto (por ejemplo, errores o vacíos en su feed de datos de producto).                                            | Su sistema interno de quejas. *Titulares de datos de energía: ingrese 0 — las obligaciones de datos de producto no aplican.* |
| Q2 — Quejas de consumidores                               | Total de quejas CDR relacionadas con consumidores o datos de consumidor (problemas de intercambio de datos, consentimiento, calidad de datos).                               | Su sistema interno de quejas.                                                                                                |
| Q3 — Quejas por tipo                                      | Un desglose por categoría utilizada en su proceso interno de quejas (por ejemplo, "Exactitud de datos", "Consentimiento", "Problemas de acceso"). Agregue una fila por tipo. | Su sistema interno de quejas.                                                                                                |
| Q4 — Quejas resueltas                                     | Total de quejas CDR de consumidores resueltas durante el periodo de reporte.                                                                                                 | Su sistema interno de quejas.                                                                                                |
| Q4.1 *(opcional)* — Resueltas, recibidas este periodo     | De Q4, cuántas se recibieron y resolvieron dentro de este mismo periodo.                                                                                                     | Su sistema interno de quejas.                                                                                                |
| Q4.2 *(opcional)* — Resueltas, recibidas periodo anterior | De Q4, cuántas se recibieron en un periodo anterior pero se resolvieron este periodo.                                                                                        | Su sistema interno de quejas.                                                                                                |
| Q5 — Días promedio para resolver (IDR)                    | Días calendario promedio desde que se recibe la queja hasta que se resuelve por resolución interna de disputas.                                                              | Su sistema interno de quejas.                                                                                                |
| Q6 — Derivadas a EDR                                      | Quejas derivadas a un esquema externo de resolución de disputas (por ejemplo, AFCA para banca o el defensor del consumidor de energía correspondiente).                      | Su sistema interno de quejas.                                                                                                |
| Q7 — Resueltas por EDR                                    | Quejas resueltas por el esquema externo de resolución de disputas.                                                                                                           | Su sistema interno de quejas.                                                                                                |

***

Solicitudes de Datos (Preguntas 8–10) [#solicitudes-de-datos-preguntas-810]

La mayoría de las cifras de solicitudes de datos provienen directamente de la pestaña **Analytics** en la Consola de Fiskil.

Para Q9 específicamente, Fiskil gestiona principalmente las solicitudes realizadas por **destinatarios de datos acreditados o intermediarios** (por ejemplo, aplicaciones o servicios que sus clientes autorizan). Fiskil generalmente no gestiona los canales de solicitud directa de consumidor a titular de datos, por lo que esta métrica suele provenir de sus propios sistemas y a menudo es 0, a menos que su sector admita este flujo y haya ocurrido.

| Pregunta                                                              | Qué pregunta                                                                                                                                                                                                                                                                                                                                                     | Dónde encontrarlo                                                                                                                              |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Q8 — Solicitudes de datos de producto                                 | Total de solicitudes recibidas por sus APIs de datos de producto durante el periodo.                                                                                                                                                                                                                                                                             | Mosaico **Product Data Requests** en Analytics. *Titulares de datos de energía: ingrese 0 — las obligaciones de datos de producto no aplican.* |
| Q9 — Solicitudes de datos de consumidor de consumidores CDR elegibles | Solicitudes realizadas directamente por consumidores a sus APIs (regla 1.13(1)(a)(i)). Fiskil generalmente no participa en este flujo directo de consumidor, por lo que esta métrica debe provenir de sus propios canales de solicitud directa. Esta obligación aún no ha comenzado para la mayoría de los titulares de datos; si eso aplica a usted, ingrese 0. | Sus sistemas internos para solicitudes directas de consumidores (no Fiskil Analytics).                                                         |
| Q10 — Solicitudes de datos de consumidor de personas acreditadas      | Solicitudes realizadas por destinatarios de datos acreditados o intermediarios en nombre de los consumidores. Este es el flujo estándar que Fiskil facilita y suele ser su principal cifra distinta de cero.                                                                                                                                                     | Mosaico **Consumer Data Requests** en Analytics.                                                                                               |

***

Rechazos de Datos de Producto (Pregunta 11) [#rechazos-de-datos-de-producto-pregunta-11]

*Titulares de datos de energía: esta sección completa no aplica. Ingrese 0 / No en todos los campos.*

| Pregunta                                              | Qué pregunta                                                                                                                                                                                                               | Dónde encontrarlo en Fiskil                                                                                                                       |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Q11 — ¿Rechazó alguna solicitud de datos de producto? | Sí/No.                                                                                                                                                                                                                     | Revise los mosaicos de rechazos en Analytics para el periodo de reporte.                                                                          |
| Q11.1 — Total de rechazos de datos de producto        | Conteo de todos los rechazos de solicitudes de datos de producto.                                                                                                                                                          | Mosaico **Total Refusals** en Analytics.                                                                                                          |
| Q11.2 — Errores 403                                   | Rechazos debidos a una amenaza detectada para el titular de datos, el Registro CDR o el consumidor.                                                                                                                        | Mosaico **Refusals (Error code 403)** en Analytics.                                                                                               |
| Q11.3 — Errores 429                                   | Rechazos debidos a umbrales de tráfico superados o detección de denegación de servicio.                                                                                                                                    | Contacte a [Soporte de Fiskil](mailto:support@fiskil.com.au) si necesita un desglose de 429 — actualmente no se muestra como un mosaico separado. |
| Q11.4 — Otros rechazos                                | Cualquier otra Regla CDR o Estándar de Datos invocado para rechazar una solicitud, con la regla citada. Bajo la implementación actual de Fiskil, esto no se admite como una vía de rechazo separada y se espera que sea 0. | Ingrese **0** para los flujos admitidos por Fiskil. Si tiene canales ajenos a Fiskil, verifique a través de sus propios sistemas internos.        |

***

Rechazos de Datos de Consumidor — Directos de Consumidores (Pregunta 12) [#rechazos-de-datos-de-consumidor--directos-de-consumidores-pregunta-12]

Fiskil gestiona principalmente las solicitudes realizadas por **destinatarios de datos acreditados o intermediarios** (por ejemplo, aplicaciones o servicios que sus clientes han autorizado). Fiskil **no** gestiona generalmente las solicitudes directas de API de consumidores individuales o consumidores empresariales hacia usted como titular de datos.

Esto significa que las métricas de la Pregunta 12 suelen provenir de **sus propios canales/procesos de solicitud directa de consumidores**, no de Fiskil Analytics.

Para la mayoría de los titulares de datos esto será poco común y a menudo **0**, pero si su sector admite solicitudes directas de consumidores y las ha recibido, debe reportarlas.

| Pregunta                                                                         | Qué pregunta                                                                                                                                                                                   | Dónde encontrarlo                                                                                                                                                              |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Q12 — ¿Rechazó solicitudes de datos de consumidor de consumidores CDR elegibles? | Sí/No. Si su sector no ha iniciado el acceso directo de consumidores por API, responda No.                                                                                                     | Esto normalmente debería ser **No / 0** a menos que haya recibido y rechazado solicitudes directas de consumidores. No proporcionado por Fiskil Analytics.                     |
| Q12.1 — Total de rechazos                                                        | Conteo de todos los rechazos a solicitudes directas de consumidores.                                                                                                                           | Esto normalmente debería ser **0** a menos que haya recibido y rechazado solicitudes directas de consumidores. No proporcionado por Fiskil Analytics.                          |
| Q12.2 — Errores 403                                                              | Rechazos debidos a una amenaza detectada.                                                                                                                                                      | Esto normalmente debería ser **0** a menos que haya recibido y rechazado solicitudes directas de consumidores con este tipo de rechazo. No proporcionado por Fiskil Analytics. |
| Q12.3 — Errores 404                                                              | Rechazos devueltos para una cuenta bloqueada o suspendida.                                                                                                                                     | Esto normalmente debería ser **0** a menos que haya recibido y rechazado solicitudes directas de consumidores con este tipo de rechazo. No proporcionado por Fiskil Analytics. |
| Q12.4 — Errores 422                                                              | Rechazos devueltos para una cuenta bloqueada o suspendida (código alternativo usado en algunos contextos de los estándares).                                                                   | Esto normalmente debería ser **0** a menos que haya recibido y rechazado solicitudes directas de consumidores con este tipo de rechazo. No proporcionado por Fiskil Analytics. |
| Q12.5 — Errores 429                                                              | Rechazos debidos a umbrales de tráfico o detección de denegación de servicio.                                                                                                                  | Esto normalmente debería ser **0** a menos que haya recibido y rechazado solicitudes directas de consumidores con este tipo de rechazo. No proporcionado por Fiskil Analytics. |
| Q12.6 — Otros rechazos                                                           | Cualquier otra Regla CDR o Estándar de Datos invocado, con la regla citada. Bajo la implementación actual de Fiskil, esto no se admite como una vía de rechazo separada y se espera que sea 0. | Esto normalmente debería ser **0**. No proporcionado por Fiskil Analytics.                                                                                                     |

***

Rechazos de Datos de Consumidor — De Personas Acreditadas (Pregunta 13) [#rechazos-de-datos-de-consumidor--de-personas-acreditadas-pregunta-13]

Esta sección refleja la Pregunta 12 pero cubre las solicitudes realizadas por **destinatarios de datos acreditados o intermediarios** en nombre de los consumidores — el flujo estándar que Fiskil facilita. Aquí es donde la mayoría de los titulares de datos tendrán cifras distintas de cero.

| Pregunta                                                                   | Qué pregunta                                                                                                                                                                                   | Dónde encontrarlo en Fiskil                                                                                                                |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Q13 — ¿Rechazó solicitudes de datos de consumidor de personas acreditadas? | Sí/No.                                                                                                                                                                                         | Revise los mosaicos de rechazos en Analytics.                                                                                              |
| Q13.1 — Total de rechazos                                                  | Conteo de todos los rechazos a solicitudes de personas acreditadas.                                                                                                                            | Mosaico **Total Refusals to share consumer data** en Analytics.                                                                            |
| Q13.2 — Errores 403                                                        | Rechazos debidos a una amenaza detectada.                                                                                                                                                      | Mosaico **Refusals (Error code 403)** en Analytics.                                                                                        |
| Q13.3 — Errores 404                                                        | Rechazos devueltos para una cuenta bloqueada o suspendida.                                                                                                                                     | Mosaico **Refusals (Error code 404)** en Analytics.                                                                                        |
| Q13.4 — Errores 422                                                        | Rechazos devueltos para una cuenta bloqueada o suspendida.                                                                                                                                     | Mosaico **Refusals (Error code 422)** en Analytics.                                                                                        |
| Q13.5 — Errores 429                                                        | Rechazos debidos a umbrales de tráfico o detección de denegación de servicio.                                                                                                                  | Contacte a [Soporte de Fiskil](mailto:support@fiskil.com.au) si necesita un desglose de 429.                                               |
| Q13.6 — Otros rechazos                                                     | Cualquier otra Regla CDR o Estándar de Datos invocado, con la regla citada. Bajo la implementación actual de Fiskil, esto no se admite como una vía de rechazo separada y se espera que sea 0. | Ingrese **0** para los flujos admitidos por Fiskil. Si tiene canales ajenos a Fiskil, verifique a través de sus propios sistemas internos. |

***

Resumen de Aplicabilidad por Sector [#resumen-de-aplicabilidad-por-sector]

| Grupo de Preguntas                         | Banca y Prestamistas No Bancarios | Titulares de Datos de Energía |
| ------------------------------------------ | --------------------------------- | ----------------------------- |
| Q1 — Quejas sobre datos de producto        | Requerido                         | No aplica — ingrese 0         |
| Q2–7 — Quejas de consumidores              | Requerido                         | Requerido                     |
| Q8 — Solicitudes de datos de producto      | Requerido                         | No aplica — ingrese 0         |
| Q9–10 — Solicitudes de datos de consumidor | Requerido                         | Requerido                     |
| Q11 — Rechazos de datos de producto        | Requerido                         | No aplica — ingrese 0 / No    |
| Q12–13 — Rechazos de datos de consumidor   | Requerido                         | Requerido                     |

***

Preguntas Frecuentes [#preguntas-frecuentes]

**¿Qué pasa si un valor es cero?**
Ingrese 0. No deje los campos numéricos en blanco.

**¿Qué cuenta como una queja CDR?**
Cualquier queja relacionada con sus obligaciones CDR — disponibilidad de datos de producto, intercambio de datos de consumidor, consentimiento y autorización, o problemas de servicio relacionados con CDR. Las quejas generales no relacionadas con CDR no necesitan contabilizarse.

**¿Cuál es la diferencia entre Q12 y Q13?**
Q12 cubre las solicitudes realizadas directamente por consumidores a sus APIs. Q13 cubre las solicitudes realizadas por destinatarios de datos acreditados o intermediarios en nombre de los consumidores — este es el flujo estándar que Fiskil facilita y donde la mayoría de los titulares de datos verán actividad.

**Necesito más detalle del que proporcionan los mosaicos de Analytics.**
La pestaña **Logs** en la Consola de Fiskil proporciona un registro completo a nivel de solicitud que puede usar para verificar o investigar los totales mostrados en Analytics. Si necesita datos que no están disponibles en la Consola, contacte a [Soporte de Fiskil](mailto:support@fiskil.com.au).

***

Recursos Adicionales [#recursos-adicionales]

* [Portal CDR](https://portal.cdr.gov.au/)
* [Reglas CDR — Regla 9.4 (Obligaciones de reporte)](https://www.legislation.gov.au/Series/F2020L00094)
* [Estándares de Datos del Consumidor](https://consumerdatastandardsaustralia.github.io/standards/)
* [Métricas](/es/data-holder/guides/telemetry/metrics)
* [Herramientas de Cumplimiento](/es/data-holder/guides/testing/compliance-tools)
* [Lista de Verificación para Producción](/es/data-holder/guides/go-live)
* [Soporte de Fiskil](mailto:support@fiskil.com.au)


---

# Create auth session (/data-api/api-reference/v3/create-auth-session)

Create an auth session before auth process.

## POST /auth/session

**Create auth session**

Create an auth session before auth process.

**Tags:** auth, v3

### Request Body

**Content-Type:** `application/json` (required)

| Field | Type | Description |
|-------|------|-------------|
| `arrangement_id` | string | Existing CDR arrangement ID to amend/update |
| `cancel_uri` | string | Where the end user will be redirected on cancellation or failure. Required for redirect flows. |
| `end_user_id` | string | The end_user that will be consenting with an external provider |
| `institution_id` | string | The institution id selected for the auth session. The user will not be able to select another institution during the consent flow. |
| `redirect_uri` | string | Where the end user will be redirected to on success. Required for redirect flow. |

**Example:**
```json
{
  "arrangement_id": "94549a73-a554-4b76-b824-d96898829751",
  "cancel_uri": "https://acme.com/cancel",
  "end_user_id": "eu_2yRHN2ag2y4p8kCtm5DOeccZEXB",
  "institution_id": "10",
  "redirect_uri": "https://acme.com/success"
}
```

### Responses

**200:** OK response.

| Field | Type | Description |
|-------|------|-------------|
| `auth_url` | string | The computed auth URL. |
| `expires_at` | integer | The computed auth URL expires at. |
| `id` | string | The client id. |
| `session_id` | string | Session Id |

**Example:**
```json
{
  "auth_url": "auth-session.com/redirect-url",
  "expires_at": 1213467,
  "id": "5qcql2s0bn9qfh1m5qd1sl4gth",
  "session_id": "ea564d-56012s4-6ds4564"
}
```

**400:** invalid_arrangement_id: Bad Request response.

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

**401:** unauthorized: Unauthorized response.

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

**404:** end_user_not_found: Not Found response.

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/auth/session" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"arrangement_id":"94549a73-a554-4b76-b824-d96898829751","cancel_uri":"https://acme.com/cancel","end_user_id":"eu_2yRHN2ag2y4p8kCtm5DOeccZEXB","institution_id":"10","redirect_uri":"https://acme.com/success"}'
```

---

# Revoke consent (/data-api/api-reference/v3/revoke-consent)

Allows a client to revoke a consent

## DELETE /consent/{arrangement_id}

**Revoke consent**

Allows a client to revoke a consent

**Tags:** consent, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `arrangement_id` | path | string | Yes | CDR arrangement ID as returned by the list consents API. |

### Responses

**204:** No Content response.

### Example Request
```bash
curl -X DELETE "https://api.fiskil.com/consent/{arrangement_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List end users (/data-api/api-reference/v3/list-end-users)

List end users belonging to a client.

## GET /end-users

**List end users**

List end users belonging to a client.

**Tags:** end-users, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `email` | query | string | No | Email address to filter end users by. |
| `page[before]` | query | string | No | When page[before] is specified, backwards pagination is achieved. |
| `page[after]` | query | string | No | When page[after] is specified, forwards pagination is achieved. |
| `page[size]` | query | integer | No | When page[size] is specified, no more than page[size] resources will be included in the response. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `end_users` | server.EnduserResponse[] | A list of end users belonging to the client. |
| `links` | object | Links to be used for pagination. |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier for this error. |
| `message` | string | Details about the error that occurred. |
| `name` | string | The name of the error. |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier for this error. |
| `message` | string | Details about the error that occurred. |
| `name` | string | The name of the error. |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/end-users" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Create end user (/data-api/api-reference/v3/create-end-user)

Creates a new end user

## POST /end-users

**Create end user**

Creates a new end user

**Tags:** end-users, v3

### Request Body

**Content-Type:** `application/json` (required)

| Field | Type | Description |
|-------|------|-------------|
| `abn` | string | Australian Business Number (ABN) of the end user if they represent a business |
| `email` | string | An End Users email address. This should be their primary email, as it is used for notifying the End User about their consents. |
| `name` | string | Name of the end user |
| `phone` | string | An End Users Phone number in E.164 format |

**Example:**
```json
{
  "abn": "51 824 753 556",
  "email": "john_starmer@gmail.com",
  "name": "John Starmer",
  "phone": "+614123456789"
}
```

### Responses

**200:** OK response.

| Field | Type | Description |
|-------|------|-------------|
| `end_user_id` | string | A unique identifier for the End User object. |

**Example:**
```json
{
  "end_user_id": "eu_2yRHN2ag2y4p8kCtm5DOeccZEXB"
}
```

**400:** end_user_already_exists: user with that email already exists

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

**401:** unauthorized: Unauthorized response.

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

**403:** insufficient_scopes: token doesn't have enough scope to access the resource

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/end-users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"abn":"51 824 753 556","email":"john_starmer@gmail.com","name":"John Starmer","phone":"+614123456789"}'
```

---

# Update end user (/data-api/api-reference/v3/update-end-user)

Update an end user

## POST /end-users/{end_user_id}

**Update end user**

Update an end user

**Tags:** end-users, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | path | string | Yes | ID of the end user |

### Request Body

**Content-Type:** `application/json` (required)

| Field | Type | Description |
|-------|------|-------------|
| `abn` | string | Australian Business Number (ABN) of the end user if they represent a business |
| `email` | string | An End Users email address. This should be their primary email, as it is used for notifying the End User about their consents. |
| `phone` | string | An End Users Phone number in E.164 format |
| `session_id` | string | ID of the session |

**Example:**
```json
{
  "abn": "51 824 753 556",
  "email": "john_starmer@gmail.com",
  "phone": "+614123456789",
  "session_id": "ses-123"
}
```

### Responses

**204:** No Content response.

**400:** end_user_already_exists: user with that email already exists

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

**404:** end_user_not_found: end user not found

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/end-users/{end_user_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"abn":"51 824 753 556","email":"john_starmer@gmail.com","phone":"+614123456789","session_id":"ses-123"}'
```

---

# Get end user by id (/data-api/api-reference/v3/get-end-user-by-id)

Finds an end user by end user id

## GET /end-users/{id}

**Get end user by id**

Finds an end user by end user id

**Tags:** end-users, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | ID of the end user to fetch. |

### Responses

**200:** OK response.

| Field | Type | Description |
|-------|------|-------------|
| `email` | string | An End Users email address. This should be their primary email, as it is used for notifying the End User about their consents. |
| `id` | string | A unique identifier for the End User object. |
| `name` | string | An End Users name. |
| `phone` | string | An End Users Phone. It is used for notifying the End User about their consents. |

**Example:**
```json
{
  "email": "john_starmer@gmail.com",
  "id": "482c0e2b-5866-46b1-b795-220b7bba45b5",
  "name": "John Starmer",
  "phone": "+614123456789"
}
```

**401:** unauthorized: Unauthorized response.

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

**404:** end_user_not_found: end user not found

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/end-users/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Delete end user (/data-api/api-reference/v3/delete-end-user)

Allows a client to delete an end user

## DELETE /end-users/{id}

**Delete end user**

Allows a client to delete an end user

**Tags:** end-users, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | The id of the end user to delete. |

### Responses

**204:** No Content response.

**404:** end_user_not_found: End user not found

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

### Example Request
```bash
curl -X DELETE "https://api.fiskil.com/end-users/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List institutions by client (/data-api/api-reference/v3/list-institutions-by-client)

Gets a list of institutions a client subscribes to.

## GET /institutions

**List institutions by client**

Gets a list of institutions a client subscribes to.

**Tags:** institutions, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `industry` | query | string | No | The type of the institution e.g. “banking” or “energy” |
| `client_id` | query | string | Yes | Your team ID. You can get this from the settings menu of the Fiskil Console |
| `sess_id` | query | string | No | The auth session id |
| `institution_mode` | query | string | No | The institution mode. If set to recommended, will load recommended institution data only |

### Responses

**200:** OK response.

**Example:**
```json
[
  {
    "icon": "https://eastpaclogo.com.au/eastpac-icon.svg",
    "id": "22",
    "industry": "banking",
    "is_accessible": true,
    "logo": "https://eastpaclogo.com.au/eastpac.svg",
    "name": "Eastpac",
    "priority": 1,
    "status": {
      "connections": {
        "status": "OUTAGE"
      }
    }
  },
  {
    "icon": "https://eastpaclogo.com.au/eastpac-icon.svg",
    "id": "22",
    "industry": "banking",
    "is_accessible": true,
    "logo": "https://eastpaclogo.com.au/eastpac.svg",
    "name": "Eastpac",
    "priority": 1,
    "status": {
      "connections": {
        "status": "OUTAGE"
      }
    }
  },
  {
    "icon": "https://eastpaclogo.com.au/eastpac-icon.svg",
    "id": "22",
    "industry": "banking",
    "is_accessible": true,
    "logo": "https://eastpaclogo.com.au/eastpac.svg",
    "name": "Eastpac",
    "priority": 1,
    "status": {
      "connections": {
        "status": "OUTAGE"
      }
    }
  },
  {
    "icon": "https://eastpaclogo.com.au/eastpac-icon.svg",
    "id": "22",
    "industry": "banking",
    "is_accessible": true,
    "logo": "https://eastpaclogo.com.au/eastpac.svg",
    "name": "Eastpac",
    "priority": 1,
    "status": {
      "connections": {
        "status": "OUTAGE"
      }
    }
  }
]
```

**400:** bad_request: EndUserID is not associated with clientID passed in request

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/institutions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get institution by id (/data-api/api-reference/v3/get-institution-by-id)

Get institution by id

## GET /institutions/{id}

**Get institution by id**

Get institution by id

**Tags:** institutions, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | string | Yes | The ID of the institution to fetch details of |

### Responses

**200:** OK response.

| Field | Type | Description |
|-------|------|-------------|
| `icon` | string | A URL to an icon for the institution |
| `id` | string | The id of the institution |
| `industry` | string | The industry of the institution e.g. “banking” or “energy” |
| `is_accessible` | boolean | Whether this institution is accessible by the teamID. Determines if institution can be used |
| `logo` | string | A URL to the logo of the institution |
| `name` | string | The name of the institution |
| `priority` | integer | The order that this institution will appear in during an auth session |
| `status` | InstitutionStatus |  |

**Example:**
```json
{
  "icon": "https://eastpaclogo.com.au/eastpac-icon.svg",
  "id": "22",
  "industry": "banking",
  "is_accessible": true,
  "logo": "https://eastpaclogo.com.au/eastpac.svg",
  "name": "Eastpac",
  "priority": 1,
  "status": {
    "connections": {
      "status": "DEGRADED"
    }
  }
}
```

**404:** institution_not_found: Not Found response.

| Field | Type | Description |
|-------|------|-------------|
| `fault` | boolean | Is the error a server-side fault? |
| `id` | string | ID is a unique identifier for this particular occurrence of the problem. |
| `message` | string | Message is a human-readable explanation specific to this occurrence of the problem. |
| `name` | string | Name is the name of this class of errors. |
| `temporary` | boolean | Is the error temporary? |
| `timeout` | boolean | Is the error a timeout? |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/institutions/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List permissions (/data-api/api-reference/v3/list-permissions)

Returns a list of Fiskil permissions.

## GET /permissions

**List permissions**

Returns a list of Fiskil permissions.

**Tags:** permissions, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `industry` | query | string | No | The industry to filter on |

### Responses

**200:** OK response.

**Example:**
```json
[
  {
    "description": "This will give the provider access to all of your transaction information",
    "industry": "banking",
    "name": "transactions",
    "scope": "bank:transactions:read",
    "standards": [
      "CDR"
    ]
  },
  {
    "description": "This will give the provider access to all of your transaction information",
    "industry": "banking",
    "name": "transactions",
    "scope": "bank:transactions:read",
    "standards": [
      "CDR"
    ]
  }
]
```

### Example Request
```bash
curl -X GET "https://api.fiskil.com/permissions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List consents (/data-api/api-reference/v3/list-consents)

List consents belonging to a client.

## GET /consent

**List consents**

List consents belonging to a client.

**Tags:** consent, v3

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | No | The ID of the end user to list consents for. |
| `active` | query | boolean | No | Filter to include only active or inactive consents. |
| `expires_before` | query | string | No | Optional RFC3339 timestamp. Only consents expiring before this time are returned. |
| `page[before]` | query | string | No | When page[before] is specified, backwards pagination is achieved. |
| `page[after]` | query | string | No | When page[after] is specified, forwards pagination is achieved. |
| `page[size]` | query | integer | No | When page[size] is specified, no more than page[size] resources will be included in the response. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `consents` | server.ConsentResponse[] | A list of consents belonging to the client. |
| `links` | object | Links to be used for pagination. |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier for this error. |
| `message` | string | Details about the error that occurred. |
| `name` | string | The name of the error. |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier for this error. |
| `message` | string | Details about the error that occurred. |
| `name` | string | The name of the error. |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/consent" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get direct debits (/data-api/api-reference/v3/getDirectDebits)

Returns list of banking account direct debits available under the authorised consent

## GET /v1/banking/acccounts/direct-debits

**Get direct debits**

Returns list of banking account direct debits available under the authorised consent

**Tags:** Direct Debits, v1, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `direct_debits` | fiskil_banking.DirectDebit[] | A list of direct debits the end user has set up |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/acccounts/direct-debits" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Handle Accounts (/data-api/api-reference/v3/getBankingAccountsV2)

returns list of banking account Accounts available under the authorised consent

## GET /v1/banking/accounts

**Handle Accounts**

returns list of banking account Accounts available under the authorised consent

**Tags:** Accounts, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `accounts` | fiskil_banking.AccountV2[] | A list of accounts for the end user |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Balances (/data-api/api-reference/v3/getBankingBalances)

Returns list of banking account balances available under the authorised consent

## GET /v1/banking/balances

**Get Balances**

Returns list of banking account balances available under the authorised consent

**Tags:** Balances, v1, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `account_id` | query | string | No | A unique identifier for the Account object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |
| `fetch` | query | string | No | fetch=true, combined with account_id, retrieves balance from data holder in real-time |
| `x-fiskil-client-ip-address` | header | string | No | Client IP address to indicate consumer present API requests. Used when fetch=true to forward to data holder. |
| `x-fiskil-client-user-agent` | header | string | No | Client User-Agent header to indicate consumer present API requests. Used when fetch=true to forward to data holder. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `balances` | fiskil_banking.Balance[] | A list of bank account balances for the end user |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**429:** Too Many Requests

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**502:** Bad Gateway

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/balances" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Handle Income (/data-api/api-reference/v3/getBankingIncome)

returns an income summary for the end-user. This is calculated over all consents associated with the end-user in real-time, and includes data from all connected bank accounts

## GET /v1/banking/income

**Handle Income**

returns an income summary for the end-user. This is calculated over all consents associated with the end-user in real-time, and includes data from all connected bank accounts

**Tags:** Income, v1, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `from` | query | string | No | Start date (inclusive) in ISO-8601 date format (YYYY-MM-DD). Defaults to 6 months before today if omitted. |
| `to` | query | string | No | End date (inclusive) in ISO-8601 date format (YYYY-MM-DD). Defaults to today if omitted. |
| `categories` | query | string[] | No | One or many income categories to include |
| `account_id` | query | string[] | No | List of account IDs to include. Pass multiple instances of account_id to include multiple accounts. Defaults to all available accounts if omitted |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `income_sources` | fiskil_banking.IncomeSource[] | A list of income sources |
| `income_summary` | object | The income summary |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/income" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Payees (/data-api/api-reference/v3/getBankingPayees)

Returns list of banking payees available under the authorised consent

## GET /v1/banking/payees

**Get Payees**

Returns list of banking payees available under the authorised consent

**Tags:** Payees, v1, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `payees` | fiskil_banking.Payee[] | A list of Payees for the given end user |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/payees" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Scheduled Payments (/data-api/api-reference/v3/getScheduledPayments)

Returns list of banking scheduled payments available under the authorised consent

## GET /v1/banking/payments/scheduled

**Get Scheduled Payments**

Returns list of banking scheduled payments available under the authorised consent

**Tags:** Scheduled Payments, v1, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `scheduled_payments` | fiskil_banking.ScheduledPayment[] | A list of scheduled payments that the end user has set up |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/payments/scheduled" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List products products (/data-api/api-reference/v3/listBankingProducts)

Returns list of banking products for a given institution

## GET /v1/banking/products

**List products products**

Returns list of banking products for a given institution

**Tags:** Products, v1, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `institution_id` | query | string | Yes | A unique identifier specifying institution. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `products` | fiskil_banking.Product[] | A list of banking products |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/products" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get product details (/data-api/api-reference/v3/getBankingProductDetailV2)

Returns detailed information about a banking product

## GET /v1/banking/products/{product_id}

**Get product details**

Returns detailed information about a banking product

**Tags:** Products, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `product_id` | path | string | Yes | A unique identifier specifying product. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `product` | object | Details of the requested product |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/products/{product_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Transactions (/data-api/api-reference/v3/getBankingTransactionsV2)

Returns list of banking transactions available under the authorised consent. For data freshness details, see /v1/data-freshness.

## GET /v1/banking/transactions

**Get Transactions**

Returns list of banking transactions available under the authorised consent. For data freshness details, see /v1/data-freshness.

**Tags:** Transactions, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `account_id` | query | string | No | A unique identifier for the Account object. |
| `from` | query | string | No | The start datetime, in RFC3339 format, from which the transaction data is requested. It will first check for posted datetime, and fallback to execution datetime if empty. Transactions without an execution or posted datetime will be excluded from results. |
| `to` | query | string | No | The end datetime, in RFC3339 format, up to which the transaction data is requested. It will first check for posted datetime, and fallback to execution datetime if empty. |
| `status` | query | string | No | Filter to include only transactions with the given status. If unset, transactions of all statuses will be returned |
| `secondary_category` | query | string | No | Include only transactions with the specified secondary category code. Optional, but can be specified multiple times for or concatenation. Defaults to include all secondary category codes if omitted. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `transactions` | fiskil_banking.TransactionV2[] | A list of transactions involving the end user |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Override Transaction Category (/data-api/api-reference/v3/overrideTransactionCategory)

Overrides the Fiskil predicted category of a specific banking transaction.

## POST /v1/banking/transactions/category

**Override Transaction Category**

Overrides the Fiskil predicted category of a specific banking transaction.

**Tags:** Transactions, v1, v2, v3, banking

### Request Body

**Content-Type:** `application/json` (required)

| Field | Type | Description |
|-------|------|-------------|
| `fiskil_transaction_id` | string | the unique identifier (fiskil_id) of the transaction. |
| `secondary_category` | string | secondary category to override the transaction with. Must be a valid secondary category from the Fiskil taxonomy. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `message` | string |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/banking/transactions/category" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Refresh Banking Transactions (/data-api/api-reference/v3/refreshBankingTransactions)

Queues an asynchronous refresh of banking transactions for all accounts connected to the end user.

## POST /v1/banking/transactions/refresh

**Refresh Banking Transactions**

Queues an asynchronous refresh of banking transactions for all accounts connected to the end user.

**Tags:** Transactions, v1, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `x-fiskil-client-ip-address` | header | string | No | End user's IP address. Used to forward to data holder for higher success rate. |
| `x-fiskil-client-user-agent` | header | string | No | End user's user-agent string. Used to forward to data holder for higher success rate. |

### Request Body

**Content-Type:** `application/json` (required)

| Field | Type | Description |
|-------|------|-------------|
| `end_user_id` | string | The unique identifier for the end user. |

### Responses

**202:** Accepted

| Field | Type | Description |
|-------|------|-------------|
| `refresh_id` | string | The unique identifier for the refresh job. |
| `status` | string | The status of the refresh job. |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**401:** Unauthorized

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**403:** Forbidden

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**404:** Not Found

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**429:** Too Many Requests

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**503:** Service Unavailable

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/banking/transactions/refresh" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Banking Transaction Refresh (/data-api/api-reference/v3/getBankingTransactionRefresh)

Query the status of a previously submitted asynchronous banking transaction refresh.

## GET /v1/banking/transactions/refresh/{refresh_id}

**Get Banking Transaction Refresh**

Query the status of a previously submitted asynchronous banking transaction refresh.

**Tags:** Transactions, v1, v2, v3, banking

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `refresh_id` | path | string | Yes | A unique identifier specifying the refresh job. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `created_at` | string | The timestamp when the refresh job was created. |
| `end_user_id` | string | The unique identifier for the end user. |
| `refresh_id` | string | The unique identifier for the refresh job. |
| `status` | string | The status of the refresh job. |
| `updated_at` | string | The timestamp when the refresh job was last updated. |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**404:** Not Found

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**503:** Service Unavailable

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/transactions/refresh/{refresh_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get customer details (/data-api/api-reference/v3/getCustomerIdentity)

Returns detailed information about the consumer identities from the most recent consent

## GET /v1/common/identity

**Get customer details**

Returns detailed information about the consumer identities from the most recent consent

**Tags:** Identity, v2, v3, common

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `institution_id` | query | string | No | A unique identifier for the Institution object. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `identities` | fiskil_identity.Identity[] | Identities contains all the customer identities for the provided end user ID |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/common/identity" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Data Freshness (/data-api/api-reference/v3/getDataFreshness)

Returns freshness information for datasets such as banking.transactions

## GET /v1/data-freshness

**Get Data Freshness**

Returns freshness information for datasets such as banking.transactions

**Tags:** Data Freshness, v1, v2, v3, core

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `dataset` | query | string | No | The dataset identifier to check freshness for (e.g. banking.transactions). |
| `account_id` | query | string | No | Filter by account ID |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `data` | fiskil_freshness.DataFreshnessEntry[] |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/data-freshness" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List energy accounts (/data-api/api-reference/v3/getEnergyAccounts)

Returns list of energy accounts belonging to the provided end user

## GET /v1/energy/accounts

**List energy accounts**

Returns list of energy accounts belonging to the provided end user

**Tags:** Accounts, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `accounts` | fiskil_energy.Account[] | A list of energy accounts belonging to the requested end user |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List energy account balances (/data-api/api-reference/v3/getEnergyBalances)

Returns list of energy account balances for accounts authorised by the end user

## GET /v1/energy/balances

**List energy account balances**

Returns list of energy account balances for accounts authorised by the end user

**Tags:** Balances, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `balances` | fiskil_energy.Balance[] |  |
| `links` | httputil.Links |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/balances" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get billing transactions (/data-api/api-reference/v3/getEnergyBilling)

Returns billing transactions for all accounts authorised by the end user

## GET /v1/energy/billing

**Get billing transactions**

Returns billing transactions for all accounts authorised by the end user

**Tags:** Billing, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User to fetch billing transactions for. |
| `account_id` | query | string | No | The account_id from the Accounts API to fetch billing transactions for. |
| `invoice_number` | query | string | No | The invoice_number from the invoices API to fetch billing transactions for. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `billing` | fiskil_energy.Billing[] |  |
| `links` | httputil.Links |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/billing" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List concessions (/data-api/api-reference/v3/getEnergyConcessions)

Returns the details of any concessions or arrangements applied to a energy accounts authorised by the end user

## GET /v1/energy/concessions

**List concessions**

Returns the details of any concessions or arrangements applied to a energy accounts authorised by the end user

**Tags:** Concessions, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `concessions` | fiskil_energy.Concession[] |  |
| `links` | httputil.Links |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/concessions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List DER (Distributed Energy Resources) (/data-api/api-reference/v3/getEnergyDer)

Obtain DER data for all service points authorised by the end user

## GET /v1/energy/der

**List DER (Distributed Energy Resources)**

Obtain DER data for all service points authorised by the end user

**Tags:** DER, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `der_records` | fiskil_energy.Der[] |  |
| `links` | httputil.Links |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/der" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List invoices (/data-api/api-reference/v3/getEnergyInvoices)

Returns the invoices for all accounts authorised by the end user

## GET /v1/energy/invoice

**List invoices**

Returns the invoices for all accounts authorised by the end user

**Tags:** Invoices, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `account_id` | query | string | No | (Optional) Account ID as returned by the Accounts API to fetch invoices for. If unset, invoices for all accounts will be returned |
| `service_point_id` | query | string | No | (Optional) Service point ID as returned by the Service Points API to fetch invoices for. If unset, invoices for all service points will be returned. |
| `invoice_number` | query | string | No | (Optional) Invoice Number for a specific invoice to fetch. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `invoices` | fiskil_energy.Invoice[] |  |
| `links` | httputil.Links |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/invoice" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List payment schedules (/data-api/api-reference/v3/getEnergyPaymentSchedules)

Returns the agreed payment schedule and details, if any, for energy accounts authorised by the end user.

## GET /v1/energy/payment-schedules

**List payment schedules**

Returns the agreed payment schedule and details, if any, for energy accounts authorised by the end user.

**Tags:** PaymentSchedules, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `payment_schedules` | fiskil_energy.PaymentSchedule[] |  |
| `links` | object |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/payment-schedules" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List Plans (/data-api/api-reference/v3/getEnergyPlans)

Obtain a list of energy plans that are offered to the market.

## GET /v1/energy/plans

**List Plans**

Obtain a list of energy plans that are offered to the market.

**Tags:** Plans, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `retailer_id` | query | string | No | A unique identifier for the Retailer object. It must be a valid CDR brand id, you can use AER website to know all available retailers. Exactly one of retailer_id or institution_id parameters is required. |
| `institution_id` | query | string | No | A unique identifier for the Institution object. It must be a valid ID fetched from Institutions API. Exactly one of retailer_id or institution_id parameters is required. Using retailer_id is recommended since CDR institutions are not as comprehensive as AER retailer list. |
| `status` | query | string | No | Filter plans by status. Allowed values: active, all. Defaults to active. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `plans` | fiskil_energy.Plan[] |  |
| `links` | object |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/plans" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get energy plan details (/data-api/api-reference/v3/getEnergyPlanDetail)

Get details of an energy plan using the plan's ID

## GET /v1/energy/plans/{plan_id}

**Get energy plan details**

Get details of an energy plan using the plan's ID

**Tags:** Plans, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `plan_id` | path | string | Yes | A unique identifier for the plan object as returned by the List Plans API. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `data` | fiskil_energy.PlanDetail |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/plans/{plan_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get service points (/data-api/api-reference/v3/getEnergyServicePoints)

Returns detailed information about service points owned by the end user that has authorised the current session

## GET /v1/energy/service-points

**Get service points**

Returns detailed information about service points owned by the end user that has authorised the current session

**Tags:** ServicePoints, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `service_points` | fiskil_energy.ServicePoint[] |  |
| `links` | object |  |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/service-points" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get usage (/data-api/api-reference/v3/getEnergyUsage)

Returns usage data for all service points associated with the end user

## GET /v1/energy/usage

**Get usage**

Returns usage data for all service points associated with the end user

**Tags:** Usage, v1, v2, v3, energy

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `end_user_id` | query | string | Yes | A unique identifier for the End User object. |
| `service_point_id` | query | string | No | A unique identifier for the Service Point object. |
| `read_start_date.oldest` | query | string | No | The start date, in yyyy-mm-dd format, from which the usage data is requested. |
| `read_start_date.newest` | query | string | No | The end date, in yyyy-mm-dd format, up to which the usage data is requested. |
| `page[before]` | query | string | No | When the page[before] is specified, backwards pagination is achieved |
| `page[after]` | query | string | No | When the page[after] is specified, forwards pagination is achieved |
| `page[size]` | query | integer | No | When the page[size] is specified, no more than page[size] resources will be included in the response's data field. This parameter is set to a sensible default, which varies depending on the endpoint. It is capped at 1000. |

### Responses

**200:** OK

| Field | Type | Description |
|-------|------|-------------|
| `usage` | fiskil_energy.Usage[] | List of energy usage reads for the end user |
| `links` | object | Links to be used for pagination |

**400:** Bad Request

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

**500:** Internal Server Error

| Field | Type | Description |
|-------|------|-------------|
| `id` | string |  |
| `message` | string |  |
| `name` | string |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/usage" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Search Customers by email (/data-holder/api-reference/cdr-reference/customerSearch)

Used during authentication to lookup customer data based on email address. Customers will be authenticated via OTP before data sharing is authorised.

## POST /auth/v1/customer/search

**Buscar Clientes**

Este endpoint se utiliza durante el proceso de autenticación para identificar al cliente a partir de los atributos definidos por la entidad financiera (por ejemplo, correo electrónico, nombre de usuario u otros identificadores).

La autenticación del cliente se realiza posteriormente mediante los mecanismos de seguridad definidos por la entidad, como Strong Customer Authentication (SCA), OTP u otros métodos equivalentes, antes de autorizar el intercambio de datos.

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** Respuesta correcta

| Field | Type | Description |
|-------|------|-------------|
| `data` | object[] |  |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/auth/v1/customer/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Fetch a customer's identity details (/data-holder/api-reference/cdr-reference/getIdentity)

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


## GET /auth/v1/customer/{customerId}

**Obtener datos de identidad del cliente**

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Map of identifying details for the customer

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | ID of the customer.
 |
| `email` | string | The customer's contact email address |
| `emailVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the email |
| `familyName` | string | The customer's family name |
| `givenName` | string | The customer's given name (or names) |
| `name` | string | A descriptive name for the customer that is suitable for display in user interfaces |
| `phoneNumber` | string | Customer's preferred telephone number in E.164 format e.g. +614123456789. For details of the E.164 format see https://www.itu.int/rec/T-REC-E.164/en. |
| `phoneNumberVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the phone number |
| `updatedAt` | string | An RFC3339 timestamp for when the customer information was most recently set |
| `address` | object | The customer's physical address. Return only as much information as you have available. Refer to the [Open ID address claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details on each field.
 |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List accounts available for sharing (/data-holder/api-reference/cdr-reference/listAccountsAuth)

Lists all accounts belonging to the customer that are available for sharing. If account selection is supported for your Data Provider, this API will be used to present the user with a list of accounts to authorize

## GET /auth/v1/customer/{customerId}/accounts

**Listar cuentas disponibles para compartir**

Enumera todas las cuentas del cliente disponibles para compartir. Si su proveedor de datos admite la selección de cuentas, esta API se utilizará para mostrar al usuario una lista de cuentas a autorizar.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Lista de cuentas

| Field | Type | Description |
|-------|------|-------------|
| `accounts` | object[] | Arreglo de cuentas disponibles para el consentimiento |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Accounts (/data-holder/api-reference/cdr-reference/listBankingAccounts)

Gets a list of accounts for a customer ID. If any account is a joint account or an organisation account the 'users' field must be populated with all related users of the energy account e.g. joint account holders, secondary users, or nominated representatives.

## GET /v1/banking/customer/{customerId}/accounts

**Get Accounts**

Gets a list of accounts for a customer ID. If any account is a joint account or an organisation account the 'users' field must be populated with all related users of the energy account e.g. joint account holders, secondary users, or nominated representatives.

**Tags:** Banking, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** A list of all accounts belonging to the customer

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingAccountListV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** The customer ID in the request URL is invalid or does not exist

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Fetch specific accounts (/data-holder/api-reference/cdr-reference/listBankingAccountsPost)

Fetch accounts based on a list of IDs specified in request body. This is used to filter to authorised accounts only.

## POST /v1/banking/customer/{customerId}/accounts

**Fetch specific accounts**

Fetch accounts based on a list of IDs specified in request body. This is used to filter to authorised accounts only.

**Tags:** Banking, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** List of the details of accounts requested

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingAccountListV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Account Detail (/data-holder/api-reference/cdr-reference/getAccountDetail)

Obtain detailed information on a single account.

## GET /v1/banking/customer/{customerId}/accounts/{accountId}

**Get Account Detail**

Obtain detailed information on a single account.

**Tags:** Banking, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Success

| Field | Type | Description |
|-------|------|-------------|
| `data` | BankingAccountDetailV3 |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/{accountId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Balances For Specific Accounts (/data-holder/api-reference/cdr-reference/listBalancesSpecificAccounts)

Obtain balances for a specified list of accounts

## POST /v1/banking/customer/{customerId}/accounts/balances

**Get Balances For Specific Accounts**

Obtain balances for a specified list of accounts

**Tags:** Banking, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json` (required)

| Field | Type | Description |
|-------|------|-------------|
| `data` | RequestAccountIds_data |  |

### Responses

**200:** List of balances for each account

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingAccountsBalanceList_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/balances" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Account Balance (/data-holder/api-reference/cdr-reference/getBalance)

Obtain the balance for a single specified account

## GET /v1/banking/customer/{customerId}/accounts/{accountId}/balance

**Get Account Balance**

Obtain the balance for a single specified account

**Tags:** Banking, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Success

| Field | Type | Description |
|-------|------|-------------|
| `data` | BankingBalance |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/{accountId}/balance" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Transactions For Account (/data-holder/api-reference/cdr-reference/getTransactions)

Obtain transactions for a specific account.

Some general notes that apply to all end points that retrieve transactions:

- Where multiple transactions are returned, transactions should be ordered according to effective date in descending order
- As the date and time for a transaction can alter depending on status and transaction type two separate date/times are included in the payload. There are still some scenarios where neither of these time stamps is available. For the purpose of filtering and ordering it is expected that the data holder will use the "effective" date/time which will be defined as:
  - Posted date/time if available, then
  - Execution date/time if available, then
  - A reasonable date/time nominated by the data holder using internal data structures
- For transaction amounts it should be assumed that a negative value indicates a reduction of the available balance on the account while a positive value indicates an increase in the available balance on the account
- For aggregated transactions (ie. groups of sub transactions reported as a single entry for the account) only the aggregated information, with as much consistent information across the subsidiary transactions as possible, is required to be shared

## GET /v1/banking/customer/{customerId}/accounts/{accountId}/transactions

**Get Transactions For Account**

Obtain transactions for a specific account.

Some general notes that apply to all end points that retrieve transactions:

- Where multiple transactions are returned, transactions should be ordered according to effective date in descending order
- As the date and time for a transaction can alter depending on status and transaction type two separate date/times are included in the payload. There are still some scenarios where neither of these time stamps is available. For the purpose of filtering and ordering it is expected that the data holder will use the "effective" date/time which will be defined as:
  - Posted date/time if available, then
  - Execution date/time if available, then
  - A reasonable date/time nominated by the data holder using internal data structures
- For transaction amounts it should be assumed that a negative value indicates a reduction of the available balance on the account while a positive value indicates an increase in the available balance on the account
- For aggregated transactions (ie. groups of sub transactions reported as a single entry for the account) only the aggregated information, with as much consistent information across the subsidiary transactions as possible, is required to be shared

**Tags:** Banking, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `min-amount` | query | string | No | Filter transactions to only transactions with amounts higher than or equal to this amount |
| `max-amount` | query | string | No | Filter transactions to only transactions with amounts less than or equal to this amount |
| `text` | query | string | No | Filter transactions to only transactions where this string value is found as a substring of either the reference or description fields. Format is arbitrary ASCII string. This parameter is optionally implemented by data holders. If it is not implemented then a response should be provided as normal without text filtering applied and an additional boolean field named isQueryParamUnsupported should be included in the meta object and set to true (whether the text parameter is supplied or not) |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** List of transactions for the account in descending order of effective timestamp

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingTransactionList_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginatedTransaction |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/{accountId}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Transaction Detail (/data-holder/api-reference/cdr-reference/getTransactionDetail)

Obtain detailed information on a transaction for a specific account

## GET /v1/banking/customer/{customerId}/accounts/{accountId}/transactions/{transactionId}

**Get Transaction Detail**

Obtain detailed information on a transaction for a specific account

**Tags:** Banking, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `transactionId` | path | string | Yes | ID of the transaction obtained from a previous call to one of the other transaction end points |

### Responses

**200:** Details of the requested transaction

| Field | Type | Description |
|-------|------|-------------|
| `data` | BankingTransactionDetail |  |

**404:** CDR compatible 404 error for when the transaction is not found. If the customer or account are not found, the resposne body is not required.

| Field | Type | Description |
|-------|------|-------------|
| `errors` | object[] |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/{accountId}/transactions/{transactionId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Direct Debits For Account (/data-holder/api-reference/cdr-reference/listDirectDebits)

Obtain direct debit authorisations for a specific account

## GET /v1/banking/customer/{customerId}/accounts/{accountId}/direct-debits

**Get Direct Debits For Account**

Obtain direct debit authorisations for a specific account

**Tags:** Banking, Direct Debits

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** List of direct debit authorisations for the queried account

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingDirectDebitAuthorisationList_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/{accountId}/direct-debits" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Direct Debits For Specific Accounts (/data-holder/api-reference/cdr-reference/listDirectDebitsSpecificAccounts)

Obtain direct debit authorisations for a specified list of accounts

## POST /v1/banking/customer/{customerId}/accounts/direct-debits

**Get Direct Debits For Specific Accounts**

Obtain direct debit authorisations for a specified list of accounts

**Tags:** Banking, Direct Debits

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json` (required)

| Field | Type | Description |
|-------|------|-------------|
| `data` | RequestAccountIds_data |  |

### Responses

**200:** List of direct debit authorisations for the accounts queried in request body

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingDirectDebitAuthorisationList_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/direct-debits" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Scheduled Payments for Account (/data-holder/api-reference/cdr-reference/listScheduledPayments)

Obtain scheduled, outgoing payments for a specific account

## GET /v1/banking/customer/{customerId}/accounts/{accountId}/payments/scheduled

**Get Scheduled Payments for Account**

Obtain scheduled, outgoing payments for a specific account

**Tags:** Banking, Scheduled Payments

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** List of scheduled payments for the queried account

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingScheduledPaymentsListV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/{accountId}/payments/scheduled" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Scheduled Payments For Specific Accounts (/data-holder/api-reference/cdr-reference/listScheduledPaymentsSpecificAccounts)

Obtain scheduled payments for a specified list of accounts

## POST /v1/banking/customer/{customerId}/payments/scheduled

**Get Scheduled Payments For Specific Accounts**

Obtain scheduled payments for a specified list of accounts

**Tags:** Banking, Scheduled Payments

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json` (required)

| Field | Type | Description |
|-------|------|-------------|
| `data` | RequestAccountIds_data |  |

### Responses

**200:** List of scheduled payments for accounts queried in request body

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingScheduledPaymentsListV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/banking/customer/{customerId}/payments/scheduled" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Payees (/data-holder/api-reference/cdr-reference/listPayees)

Obtain a list of pre-registered payees.

## GET /v1/banking/customer/{customerId}/payees

**Get Payees**

Obtain a list of pre-registered payees.

**Tags:** Banking, Payees

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `type` | query | string | No | Filter on the payee type field.  In addition to normal type field values, ALL can be specified to retrieve all payees.  If absent the assumed value is ALL |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** List of payees the user has registered

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingPayeeListV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/payees" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Payee Detail (/data-holder/api-reference/cdr-reference/getPayeeDetail)

Obtain detailed information on a single payee.

Note that the payee sub-structure should be selected to represent the payment destination only rather than any known characteristics of the payment recipient.

## GET /v1/banking/customer/{customerId}/payees/{payeeId}

**Get Payee Detail**

Obtain detailed information on a single payee.

Note that the payee sub-structure should be selected to represent the payment destination only rather than any known characteristics of the payment recipient.

**Tags:** Banking, Payees

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `payeeId` | path | string | Yes | The ID used to locate the details of a particular payee |

### Responses

**200:** Details of the requested payee

| Field | Type | Description |
|-------|------|-------------|
| `data` | BankingPayeeDetailV2 |  |

**404:** CDR compatible 404 error for when the payee is not found. If the customer is not found, the response body is not required.

| Field | Type | Description |
|-------|------|-------------|
| `errors` | object[] |  |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/payees/{payeeId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Energy Accounts (/data-holder/api-reference/cdr-reference/listAccounts)

List all accounts available for data sharing. This will be used to support account selection during the authorisation.

## GET /v1/energy/customer/{customerId}/accounts

**Get Energy Accounts**

List all accounts available for data sharing. This will be used to support account selection during the authorisation.

**Tags:** Energy, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Accounts belonging to the authenticated user they can use for data sharing

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyAccountListResponseV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Fetch specific Energy Accounts (/data-holder/api-reference/cdr-reference/listAccountspost)

Fetch the details of specific energy accounts that have been authorised by the user

## POST /v1/energy/customer/{customerId}/accounts

**Fetch specific Energy Accounts**

Fetch the details of specific energy accounts that have been authorised by the user

**Tags:** Energy, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** List of details for the accounts requested

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyAccountListResponseV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Energy Account Detail (/data-holder/api-reference/cdr-reference/getAccount)

Obtain detailed information for a specific energy account

## GET /fdx/v6/customer/{customerId}/accounts/{accountId}

**Get detailed information for a specific account**

Get account balances, liabilities, and other information.


**Tags:** Account Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** The full details of an investment, loan, deposit, or line of credit account


**404:** 

**409:** Account is closed [optional]


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported [optional]


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Agreed Payment Schedule (/data-holder/api-reference/cdr-reference/getPaymentSchedule)

Obtain the agreed payment schedule and details, if any, for a specific energy account.
Some general notes about this end point:
  * This API describes how the consumer has elected to pay for their account
  * Payments initiated by the consumer are classified as manual payments. The billing frequency is captured for manual payments. The consumer may choose to pay on a different schedule/frequency. The payment method and frequency is not captured for manual payments
  * Payments that can be initiated by the retailer, based on a consumer's preferences and permission, include payments based on a direct debit, card debit or digital wallet setup. Each of these requires a payment frequency to be provided along with other relevant fields
  * Information about payment plans related to debt repayments or arrangements due to hardship is not captured within this API


## GET /v1/energy/customer/{customerId}/accounts/{accountId}/payment-schedule

**Get Agreed Payment Schedule**

Obtain the agreed payment schedule and details, if any, for a specific energy account.
Some general notes about this end point:
  * This API describes how the consumer has elected to pay for their account
  * Payments initiated by the consumer are classified as manual payments. The billing frequency is captured for manual payments. The consumer may choose to pay on a different schedule/frequency. The payment method and frequency is not captured for manual payments
  * Payments that can be initiated by the retailer, based on a consumer's preferences and permission, include payments based on a direct debit, card debit or digital wallet setup. Each of these requires a payment frequency to be provided along with other relevant fields
  * Information about payment plans related to debt repayments or arrangements due to hardship is not captured within this API


**Tags:** Energy, Payment Schedule

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** The customer's payment schedule

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyPaymentScheduleResponse_data |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts/{accountId}/payment-schedule" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Concessions (/data-holder/api-reference/cdr-reference/getConcessions)

Obtain the details of any concessions or arrangements applied to a specific energy account

## GET /v1/energy/customer/{customerId}/accounts/{accountId}/concessions

**Get Concessions**

Obtain the details of any concessions or arrangements applied to a specific energy account

**Tags:** Energy, Concessions

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** List of concessions for the provided energy account

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyConcessionsResponse_data |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts/{accountId}/concessions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Balance For Energy Account (/data-holder/api-reference/cdr-reference/getBalanceForAccount)

Obtain the current balance for a specific account

## GET /v1/energy/customer/{customerId}/accounts/{accountId}/balance

**Get Balance For Energy Account**

Obtain the current balance for a specific account

**Tags:** Energy, Balances

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** The current balance for the queried energy account

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyBalanceResponse_data |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts/{accountId}/balance" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Balances For Specific Energy Accounts (/data-holder/api-reference/cdr-reference/listBalancesForAccounts)

Obtain the current balance for a specified set of accounts

## POST /v1/energy/customer/{customerId}/accounts/balances

**Get Balances For Specific Energy Accounts**

Obtain the current balance for a specified set of accounts

**Tags:** Energy, Balances

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** Successful response

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyBalanceListResponse_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts/balances" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Invoices For Account (/data-holder/api-reference/cdr-reference/getInvoicesForAccount)

Obtain the invoices for a specific account

## GET /v1/energy/customer/{customerId}/accounts/{accountId}/invoices

**Get Invoices For Account**

Obtain the invoices for a specific account

**Tags:** Energy, Invoices

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** List of invoices for the account matching the query

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyInvoiceListResponse_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts/{accountId}/invoices" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Invoices For Specific Accounts (/data-holder/api-reference/cdr-reference/listInvoicesForAccounts)

Obtain invoices for a specified set of accounts

## POST /v1/energy/customer/{customerId}/accounts/invoices

**Get Invoices For Specific Accounts**

Obtain invoices for a specified set of accounts

**Tags:** Energy, Invoices

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** List of invoices for the queried accounts

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyInvoiceListResponse_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts/invoices" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Billing For Account (/data-holder/api-reference/cdr-reference/getBillingForAccount)

Obtain the billing transactions for a specific account

## GET /v1/energy/customer/{customerId}/accounts/{accountId}/billing

**Get Billing For Account**

Obtain the billing transactions for a specific account

**Tags:** Energy, Billing

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Successful response

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyBillingListResponseV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts/{accountId}/billing" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Billing For Specific Accounts (/data-holder/api-reference/cdr-reference/listBillingForAccounts)

Obtain billing for a specified set of authorised accounts

## POST /v1/energy/customer/{customerId}/accounts/billing

**Get Billing For Specific Accounts**

Obtain billing for a specified set of authorised accounts

**Tags:** Energy, Billing

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** List of billing transactions for the requested accounts

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyBillingListResponseV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts/billing" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Customer Detail (/data-holder/api-reference/cdr-reference/getCustomerDetail)

Obtain detailed information on the authorised customer within the current session.

## GET /v1/common/customer/{customerId}/detail

**Get Customer Detail**

Obtain detailed information on the authorised customer within the current session.

**Tags:** Common

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Details of the customer with the ID given in the URL path

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseCommonCustomerDetailV2_data |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/common/customer/{customerId}/detail" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Servicepoint Search (AEMO) (/data-holder/api-reference/cdr-reference/servicePointSearch)

Search energy customer servicepoint data by account IDs. This is only required to be implemented for Energy data holders.

## POST /v1/common/customer/{customerId}/servicepoints/search

**Servicepoint Search (AEMO)**

Search energy customer servicepoint data by account IDs. This is only required to be implemented for Energy data holders.

**Tags:** Common

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** List of Servicepoints (NMIs) and AEMO participant IDs for the queried accounts

| Field | Type | Description |
|-------|------|-------------|
| `accountId` | string | The ID of the account |
| `participantId` | string | The AEMO participant ID of the retailer |
| `servicePointId` | string | The ID of the service point to which this transaction applies if any |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/common/customer/{customerId}/servicepoints/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Get Instalment Plans for Account (/data-holder/api-reference/cdr-reference/listInstalmentPlans)

Obtain instalment plans for a single specified account. The response must be ordered by plan `creationDate` in descending order.

An instalment plan describes the terms of repayment for a specified loan amount such as a Buy Now, Pay Later (BNPL) purchase or a specific card transaction.

If `isInstalmentDetailAvailable` was specified as `true` for the provided `accountId` but no plans match the provided parameters, an empty array must be returned. If `isInstalmentDetailAvailable` was specified as `false` for the provided `accountId`, then the endpoint may respond with a `404 Resource Not Implemented` error.

## GET /v1/banking/customer/{customerId}/accounts/{accountId}/payments/plans

**Get Instalment Plans for Account**

Obtain instalment plans for a single specified account. The response must be ordered by plan `creationDate` in descending order.

An instalment plan describes the terms of repayment for a specified loan amount such as a Buy Now, Pay Later (BNPL) purchase or a specific card transaction.

If `isInstalmentDetailAvailable` was specified as `true` for the provided `accountId` but no plans match the provided parameters, an empty array must be returned. If `isInstalmentDetailAvailable` was specified as `false` for the provided `accountId`, then the endpoint may respond with a `404 Resource Not Implemented` error.

**Tags:** Banking, Instalment Plans

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `plan-status` | query | string | No | Allows for the filtering of plans based on their schedule status:
- `ACTIVE` requests plans where one or more scheduled instalments have `isPaid` equal to `false`.
- `INACTIVE` requests plans where all scheduled instalments have `isPaid` equal to `true`.
- `ALL` requests all `ACTIVE` and `INACTIVE` plans. |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** List of instalment plans for the queried account

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingInstalmentPlanList_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/{accountId}/payments/plans" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Instalment Plans For Specific Accounts (/data-holder/api-reference/cdr-reference/listInstalmentPlansSpecificAccounts)

Obtain instalment plans for a specified list of accounts. The response must be ordered by plan `creationDate` in descending order.

If instalments are not supported for any account type, the endpoint may respond with a `404 Resource Not Implemented` error.

## POST /v1/banking/customer/{customerId}/accounts/payments/plans

**Get Instalment Plans For Specific Accounts**

Obtain instalment plans for a specified list of accounts. The response must be ordered by plan `creationDate` in descending order.

If instalments are not supported for any account type, the endpoint may respond with a `404 Resource Not Implemented` error.

**Tags:** Banking, Instalment Plans

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `plan-status` | query | string | No | Allows for the filtering of plans based on their schedule status:
- `ACTIVE` requests plans where one or more scheduled instalments have `isPaid` equal to `false`.
- `INACTIVE` requests plans where all scheduled instalments have `isPaid` equal to `true`.
- `ALL` requests all `ACTIVE` and `INACTIVE` plans. |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** List of instalment plans for the accounts queried in request body

| Field | Type | Description |
|-------|------|-------------|
| `data` | ResponseBankingInstalmentPlanList_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

**422:** 

### Example Request
```bash
curl -X POST "https://api.fiskil.com/v1/banking/customer/{customerId}/accounts/payments/plans" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Search Customers by email (/data-holder/api-reference/fdx/customerSearch)

Used during authentication to lookup customer data based on email address. Customers will be authenticated via OTP before data sharing is authorised.

## POST /auth/v1/customer/search

**Buscar Clientes**

Este endpoint se utiliza durante el proceso de autenticación para identificar al cliente a partir de los atributos definidos por la entidad financiera (por ejemplo, correo electrónico, nombre de usuario u otros identificadores).

La autenticación del cliente se realiza posteriormente mediante los mecanismos de seguridad definidos por la entidad, como Strong Customer Authentication (SCA), OTP u otros métodos equivalentes, antes de autorizar el intercambio de datos.

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** Respuesta correcta

| Field | Type | Description |
|-------|------|-------------|
| `data` | object[] |  |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/auth/v1/customer/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Fetch a customer's identity details (/data-holder/api-reference/fdx/getIdentity)

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


## GET /auth/v1/customer/{customerId}

**Obtener datos de identidad del cliente**

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Map of identifying details for the customer

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | ID of the customer.
 |
| `email` | string | The customer's contact email address |
| `emailVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the email |
| `familyName` | string | The customer's family name |
| `givenName` | string | The customer's given name (or names) |
| `name` | string | A descriptive name for the customer that is suitable for display in user interfaces |
| `phoneNumber` | string | Customer's preferred telephone number in E.164 format e.g. +614123456789. For details of the E.164 format see https://www.itu.int/rec/T-REC-E.164/en. |
| `phoneNumberVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the phone number |
| `updatedAt` | string | An RFC3339 timestamp for when the customer information was most recently set |
| `address` | object | The customer's physical address. Return only as much information as you have available. Refer to the [Open ID address claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details on each field.
 |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List accounts available for sharing (/data-holder/api-reference/fdx/listAccountsAuth)

Lists all accounts belonging to the customer that are available for sharing. If account selection is supported for your Data Provider, this API will be used to present the user with a list of accounts to authorize

## GET /auth/v1/customer/{customerId}/accounts

**Listar cuentas disponibles para compartir**

Enumera todas las cuentas del cliente disponibles para compartir. Si su proveedor de datos admite la selección de cuentas, esta API se utilizará para mostrar al usuario una lista de cuentas a autorizar.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Lista de cuentas

| Field | Type | Description |
|-------|------|-------------|
| `accounts` | object[] | Arreglo de cuentas disponibles para el consentimiento |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Fetch specific accounts (/data-holder/api-reference/fdx/getSpecificAccounts)

Fetch a specified set of accounts. When a client requests all accounts, this API will be used
to filter to only the accounts that were authorized by the end user.


## POST /fdx/v6/customer/{customerId}/accounts

**Fetch specific accounts**

Fetch a specified set of accounts. When a client requests all accounts, this API will be used
to filter to only the accounts that were authorized by the end user.


**Tags:** Account Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Request Body

**Content-Type:** `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | object | The set of accounts to fetch |

**Example:**
```json
{
  "data": {
    "accountIds": [
      "depositAccount0000001",
      "loanAccount0000001"
    ]
  }
}
```

### Responses

**200:** An array of accounts.

**Note:** Each object in the accounts array is expected to contain at least one account type.


**Example:**
```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "accounts": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "accountId": "depositAccount0000001",
      "accountType": "CHECKING",
      "accountNumberDisplay": "5820",
      "productName": "Checking",
      "nickname": "Main Checking",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOAN_ACCOUNT",
      "accountId": "loanAccount0000001",
      "accountType": "LOAN",
      "accountNumberDisplay": "4704",
      "productName": "Loan",
      "nickname": "Primary Loan",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "LOC_ACCOUNT",
      "accountId": "locAccount0000001",
      "accountType": "LINEOFCREDIT",
      "accountNumberDisplay": "8200",
      "productName": "Line of Credit",
      "nickname": "First plaidypus LOC",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "accountCategory": "INVESTMENT_ACCOUNT",
      "accountId": "investmentAccount0000001",
      "accountType": "TAXABLE",
      "accountNumberDisplay": "1050",
      "productName": "Brokerage Account",
      "nickname": "First plaidypus Brokerage",
      "status": "OPEN",
      "currency": {
        "currencyCode": "USD"
      }
    }
  ]
}
```

**404:** 

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"accountIds":["depositAccount0000001","loanAccount0000001"]}}'
```

---

# Get detailed information for a specific account (/data-holder/api-reference/fdx/getAccount)

Get account balances, liabilities, and other information.


## GET /fdx/v6/customer/{customerId}/accounts/{accountId}

**Get detailed information for a specific account**

Get account balances, liabilities, and other information.


**Tags:** Account Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** The full details of an investment, loan, deposit, or line of credit account


**404:** 

**409:** Account is closed [optional]


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported [optional]


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get an account's contact information (/data-holder/api-reference/fdx/getAccountContact)

Get contact information on the account.


## GET /fdx/v6/customer/{customerId}/accounts/{accountId}/contact

**Get an account's contact information**

Get contact information on the account.


**Tags:** Personal Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Details used to verify an account


| Field | Type | Description |
|-------|------|-------------|
| `holders` | AccountHolder[] | Owners of the account.
 |
| `emails` | string[] | Email addresses associated with the account
 |
| `addresses` | DeliveryAddress[] | Physical mail addresses associated with the account
 |
| `telephones` | TelephoneNumber[] | Telephone numbers associated with the account
 |

**404:** 

**409:** Account is closed


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}/contact" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get payment networks supported by the account (/data-holder/api-reference/fdx/getAccountPaymentNetworks)

Get payment networks supported by an account, for example ACH (Automated Clearing House).


## GET /fdx/v6/customer/{customerId}/accounts/{accountId}/payment-networks

**Get payment networks supported by the account**

Get payment networks supported by an account, for example ACH (Automated Clearing House).


**Tags:** Payment Networks Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Information required to execute a payment transaction against this account


**Example:**
```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "paymentNetworks": [
    {
      "bankId": "010088889",
      "identifier": "1111222233335820",
      "type": "US_ACH",
      "transferIn": true,
      "transferOut": true
    }
  ]
}
```

**404:** 

**409:** Account is closed


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}/payment-networks" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Search for account transactions (/data-holder/api-reference/fdx/searchForAccountTransactions)

List all account transactions.
Fiskil always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`,
and expects the time filters to be based on the `postedTimestamp`.


## GET /fdx/v6/customer/{customerId}/accounts/{accountId}/transactions

**Search for account transactions**

List all account transactions.
Fiskil always queries this endpoint using a `startTime` and an `endTime`, for example, `/accounts/{accountId}/transactions?startTime=2022-01-30&endTime=2022-05-30`,
and expects the time filters to be based on the `postedTimestamp`.


**Tags:** Account Transactions

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Paginated collection of transactions.


**Example:**
```json
{
  "page": {
    "nextOffset": "B47D80MVP23T"
  },
  "transactions": [
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "CHECK",
      "checkNumber": 1234,
      "payee": "ACME LLC",
      "transactionId": "depositTransaction000000001",
      "postedTimestamp": "2022-04-06T00:00:00.000Z",
      "transactionTimestamp": "2022-04-05T00:00:00.000Z",
      "description": "check for latest ACME invoice",
      "debitCreditMemo": "DEBIT",
      "status": "PENDING",
      "amount": 400
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "ADJUSTMENT",
      "transactionId": "depositTransaction000000002",
      "postedTimestamp": "2022-04-07T00:00:00.000Z",
      "transactionTimestamp": "2022-04-07T00:00:00.000Z",
      "description": "reconciliation/adjustment of bank statement error",
      "debitCreditMemo": "DEBIT",
      "status": "POSTED",
      "amount": 0.8
    },
    {
      "accountCategory": "DEPOSIT_ACCOUNT",
      "transactionType": "ATMDEPOSIT",
      "transactionId": "depositTransaction000000003",
      "postedTimestamp": "2022-04-08T00:00:00.000Z",
      "transactionTimestamp": "2022-04-08T00:00:00.000Z",
      "description": "ATM cash deposit location #1234",
      "debitCreditMemo": "CREDIT",
      "status": "POSTED",
      "amount": 101.8
    }
  ]
}
```

**404:** 

**409:** Account is closed


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Search for statements (/data-holder/api-reference/fdx/searchForAccountStatements)

Get account statements.


## GET /fdx/v6/customer/{customerId}/accounts/{accountId}/statements

**Search for statements**

Get account statements.


**Tags:** Account Statements

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Paginated list of available statements


**Example:**
```json
{
  "page": {
    "nextOffset": "B47D80MVP23T",
    "totalElements": 3
  },
  "statements": [
    {
      "accountId": "10001",
      "statementId": "20001",
      "statementDate": "2024-01-15",
      "description": "January 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20001",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        },
        {
          "href": "/accounts/10001/statements/20001/download",
          "rel": "download",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "AVAILABLE"
    },
    {
      "accountId": "10001",
      "statementId": "20002",
      "statementDate": "2024-02-15",
      "description": "February 2024 Monthly Statement",
      "links": [
        {
          "href": "/accounts/10001/statements/20002",
          "rel": "self",
          "action": "GET",
          "types": [
            "application/pdf"
          ]
        }
      ],
      "status": "PROCESSING"
    }
  ]
}
```

**404:** 

**409:** Account is closed


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}/statements" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get account statement (/data-holder/api-reference/fdx/getAccountStatement)

Get account statement PDF


## GET /fdx/v6/customer/{customerId}/accounts/{accountId}/statements/{statementId}

**Get account statement**

Get account statement PDF


**Tags:** Account Statements

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** A pdf of an account statement


**404:** 

**409:** Account is closed


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}/statements/{statementId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get asset transfer details for this account (/data-holder/api-reference/fdx/getAccountAssetTransferNetworks)

Get asset transfer networks supported by an account. For example, Automated Customer Account Transfer Service (ACATS).


## GET /fdx/v6/customer/{customerId}/accounts/{accountId}/asset-transfer-networks

**Get asset transfer details for this account**

Get asset transfer networks supported by an account. For example, Automated Customer Account Transfer Service (ACATS).


**Tags:** Asset Transfer Networks Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Information required to execute an asset transfer transaction against this account


| Field | Type | Description |
|-------|------|-------------|
| `assetTransferNetworks` | AssetTransferNetwork[] | A paginated array of asset transfer networks for the account
 |

**Example:**
```json
{
  "assetTransferNetworks": [
    {
      "identifier": "23348817826",
      "identifierType": "ACCOUNT_NUMBER",
      "institutionName": "First Plaidypus Bank",
      "institutionId": "FPB",
      "type": "US_ACATS",
      "jointAccount": true
    }
  ]
}
```

**404:** 

**409:** Account is closed


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}/asset-transfer-networks" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Accounts (/data-holder/api-reference/psd2/getAccounts)

Retrieve a list of payment accounts that the customer has consented to share. This endpoint returns basic account information including account identifiers, names, and types.


## GET /accounts

**Get Accounts**

Retrieve a list of payment accounts that the customer has consented to share. This endpoint returns basic account information including account identifiers, names, and types.


**Tags:** Account Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Successfully retrieved account list

| Field | Type | Description |
|-------|------|-------------|
| `data` | Account[] |  |
| `links` | Links |  |
| `meta` | Meta |  |

**400:** 

**401:** 

**403:** 

**429:** 

**500:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Account Details (/data-holder/api-reference/psd2/getAccountDetails)

Retrieve detailed information for a specific account, including account metadata, product information, and account status.


## GET /accounts/{accountId}

**Get Account Details**

Retrieve detailed information for a specific account, including account metadata, product information, and account status.


**Tags:** Account Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Successfully retrieved account details

| Field | Type | Description |
|-------|------|-------------|
| `data` | AccountDetails |  |
| `links` | Links |  |
| `meta` | Meta |  |

**400:** 

**401:** 

**403:** 

**404:** 

**429:** 

**500:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/accounts/{accountId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Account Balances (/data-holder/api-reference/psd2/getAccountBalances)

Retrieve current and available balances for a specific account. Returns balance information including currency and balance types.


## GET /accounts/{accountId}/balances

**Get Account Balances**

Retrieve current and available balances for a specific account. Returns balance information including currency and balance types.


**Tags:** Account Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Successfully retrieved account balances

| Field | Type | Description |
|-------|------|-------------|
| `data` | Balance[] |  |
| `links` | Links |  |
| `meta` | Meta |  |

**400:** 

**401:** 

**403:** 

**404:** 

**429:** 

**500:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/accounts/{accountId}/balances" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Account Transactions (/data-holder/api-reference/psd2/getAccountTransactions)

Retrieve transaction history for a specific account. Supports filtering by date range and pagination for large result sets.


## GET /accounts/{accountId}/transactions

**Get Account Transactions**

Retrieve transaction history for a specific account. Supports filtering by date range and pagination for large result sets.


**Tags:** Transaction Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Successfully retrieved transaction list

| Field | Type | Description |
|-------|------|-------------|
| `data` | Transaction[] |  |
| `links` | Links |  |
| `meta` | Meta |  |

**400:** 

**401:** 

**403:** 

**404:** 

**429:** 

**500:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/accounts/{accountId}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Transaction Details (/data-holder/api-reference/psd2/getTransactionDetails)

Retrieve detailed information for a specific transaction, including extended transaction data and merchant information.


## GET /accounts/{accountId}/transactions/{transactionId}

**Get Transaction Details**

Retrieve detailed information for a specific transaction, including extended transaction data and merchant information.


**Tags:** Transaction Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Successfully retrieved transaction details

| Field | Type | Description |
|-------|------|-------------|
| `data` | TransactionDetails |  |
| `links` | Links |  |
| `meta` | Meta |  |

**400:** 

**401:** 

**403:** 

**404:** 

**429:** 

**500:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/accounts/{accountId}/transactions/{transactionId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Customer Information (/data-holder/api-reference/psd2/getCustomer)

Retrieve basic customer information associated with the authenticated session. Used for customer identification and verification.


## GET /customer

**Get Customer Information**

Retrieve basic customer information associated with the authenticated session. Used for customer identification and verification.


**Tags:** Customer Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Successfully retrieved customer information

| Field | Type | Description |
|-------|------|-------------|
| `data` | Customer |  |
| `links` | Links |  |
| `meta` | Meta |  |

**400:** 

**401:** 

**403:** 

**429:** 

**500:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/customer" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Search Customers by email (/data-holder/api-reference/latam-chile/customerSearch)

Used during authentication to lookup customer data based on email address. Customers will be authenticated via OTP before data sharing is authorised.

## POST /auth/v1/customer/search

**Buscar Clientes**

Este endpoint se utiliza durante el proceso de autenticación para identificar al cliente a partir de los atributos definidos por la entidad financiera (por ejemplo, correo electrónico, nombre de usuario u otros identificadores).

La autenticación del cliente se realiza posteriormente mediante los mecanismos de seguridad definidos por la entidad, como Strong Customer Authentication (SCA), OTP u otros métodos equivalentes, antes de autorizar el intercambio de datos.

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** Respuesta correcta

| Field | Type | Description |
|-------|------|-------------|
| `data` | object[] |  |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/auth/v1/customer/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Fetch a customer's identity details (/data-holder/api-reference/latam-chile/getIdentity)

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


## GET /auth/v1/customer/{customerId}

**Obtener datos de identidad del cliente**

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Map of identifying details for the customer

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | ID of the customer.
 |
| `email` | string | The customer's contact email address |
| `emailVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the email |
| `familyName` | string | The customer's family name |
| `givenName` | string | The customer's given name (or names) |
| `name` | string | A descriptive name for the customer that is suitable for display in user interfaces |
| `phoneNumber` | string | Customer's preferred telephone number in E.164 format e.g. +614123456789. For details of the E.164 format see https://www.itu.int/rec/T-REC-E.164/en. |
| `phoneNumberVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the phone number |
| `updatedAt` | string | An RFC3339 timestamp for when the customer information was most recently set |
| `address` | object | The customer's physical address. Return only as much information as you have available. Refer to the [Open ID address claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details on each field.
 |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List accounts available for sharing (/data-holder/api-reference/latam-chile/listAccountsAuth)

Lists all accounts belonging to the customer that are available for sharing. If account selection is supported for your Data Provider, this API will be used to present the user with a list of accounts to authorize

## GET /auth/v1/customer/{customerId}/accounts

**Listar cuentas disponibles para compartir**

Enumera todas las cuentas del cliente disponibles para compartir. Si su proveedor de datos admite la selección de cuentas, esta API se utilizará para mostrar al usuario una lista de cuentas a autorizar.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Lista de cuentas

| Field | Type | Description |
|-------|------|-------------|
| `accounts` | object[] | Arreglo de cuentas disponibles para el consentimiento |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List Accounts (/data-holder/api-reference/latam-chile/listAccounts)

Returns a paginated list of all accounts belonging to the authenticated customer. Each account includes details such as type, status, currency, ownership, and applicable conditions.

## GET /v1/energy/customer/{customerId}/accounts

**Get Energy Accounts**

List all accounts available for data sharing. This will be used to support account selection during the authorisation.

**Tags:** Energy, Accounts

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** Accounts belonging to the authenticated user they can use for data sharing

| Field | Type | Description |
|-------|------|-------------|
| `data` | EnergyAccountListResponseV2_data |  |
| `links` | LinksPaginated |  |
| `meta` | MetaPaginated |  |

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/v1/energy/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Account Detail (/data-holder/api-reference/latam-chile/getAccount)

Returns detailed information about a specific account identified by its account ID, including type, status, currency, ownership, branch, product, and conditions.

## GET /fdx/v6/customer/{customerId}/accounts/{accountId}

**Get detailed information for a specific account**

Get account balances, liabilities, and other information.


**Tags:** Account Information

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |
| `` |  | object | No |  |

### Responses

**200:** The full details of an investment, loan, deposit, or line of credit account


**404:** 

**409:** Account is closed [optional]


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account is closed
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**422:** Account type not supported [optional]


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for account type not supported
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**500:** Internal server error


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for internal server error
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

**503:** Scheduled maintenance


| Field | Type | Description |
|-------|------|-------------|
| `code` | integer | FDX Error code for scheduled maintenance
 |
| `message` | string | End user displayable information which might help the customer diagnose an error
 |
| `debugMessage` | string | Message used to debug the root cause of the error. Provider can include an error GUID in message for their use
 |

### Example Request
```bash
curl -X GET "https://api.fiskil.com/fdx/v6/customer/{customerId}/accounts/{accountId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# Get Account Balance (/data-holder/api-reference/latam-chile/getAccountBalance)

Returns the current balance and historical balance entries for a specific account. Supports date range filtering via query parameters.

---

# List Account Transactions (/data-holder/api-reference/latam-chile/listAccountTransactions)

Returns a paginated list of transactions for a specific account. Supports date range filtering. Each transaction includes debtor/creditor details, merchant information, and card instruments.

---

# Get Customer (Natural Person) (/data-holder/api-reference/latam-chile/getCustomerPN)

Returns personal information for a natural person (persona natural) customer, including identity details (RUT), contact information, address, occupation, income range, PEP status, and KYC status.

---

# Search Customers by email (/data-holder/api-reference/latam-colombia/customerSearch)

Used during authentication to lookup customer data based on email address. Customers will be authenticated via OTP before data sharing is authorised.

## POST /auth/v1/customer/search

**Buscar Clientes**

Este endpoint se utiliza durante el proceso de autenticación para identificar al cliente a partir de los atributos definidos por la entidad financiera (por ejemplo, correo electrónico, nombre de usuario u otros identificadores).

La autenticación del cliente se realiza posteriormente mediante los mecanismos de seguridad definidos por la entidad, como Strong Customer Authentication (SCA), OTP u otros métodos equivalentes, antes de autorizar el intercambio de datos.

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** Respuesta correcta

| Field | Type | Description |
|-------|------|-------------|
| `data` | object[] |  |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/auth/v1/customer/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Fetch a customer's identity details (/data-holder/api-reference/latam-colombia/getIdentity)

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


## GET /auth/v1/customer/{customerId}

**Obtener datos de identidad del cliente**

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Map of identifying details for the customer

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | ID of the customer.
 |
| `email` | string | The customer's contact email address |
| `emailVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the email |
| `familyName` | string | The customer's family name |
| `givenName` | string | The customer's given name (or names) |
| `name` | string | A descriptive name for the customer that is suitable for display in user interfaces |
| `phoneNumber` | string | Customer's preferred telephone number in E.164 format e.g. +614123456789. For details of the E.164 format see https://www.itu.int/rec/T-REC-E.164/en. |
| `phoneNumberVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the phone number |
| `updatedAt` | string | An RFC3339 timestamp for when the customer information was most recently set |
| `address` | object | The customer's physical address. Return only as much information as you have available. Refer to the [Open ID address claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details on each field.
 |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List accounts available for sharing (/data-holder/api-reference/latam-colombia/listAccountsAuth)

Lists all accounts belonging to the customer that are available for sharing. If account selection is supported for your Data Provider, this API will be used to present the user with a list of accounts to authorize

## GET /auth/v1/customer/{customerId}/accounts

**Listar cuentas disponibles para compartir**

Enumera todas las cuentas del cliente disponibles para compartir. Si su proveedor de datos admite la selección de cuentas, esta API se utilizará para mostrar al usuario una lista de cuentas a autorizar.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Lista de cuentas

| Field | Type | Description |
|-------|------|-------------|
| `accounts` | object[] | Arreglo de cuentas disponibles para el consentimiento |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List Accounts (/data-holder/api-reference/latam-colombia/coListAccounts)

Returns a paginated list of all accounts belonging to the authenticated customer. Each account includes details such as type, status, currency, ownership, and applicable conditions.

---

# Get Account Detail (/data-holder/api-reference/latam-colombia/coGetAccount)

Returns detailed information about a specific account identified by its account ID, including type, status, currency, ownership, branch, product, and conditions.

---

# Get Account Balance (/data-holder/api-reference/latam-colombia/coGetAccountBalance)

Returns the current balance and historical balance entries for a specific account. Supports date range filtering via query parameters.

---

# List Account Transactions (/data-holder/api-reference/latam-colombia/coListAccountTransactions)

Returns a paginated list of transactions for a specific account. Supports date range filtering. Each transaction includes debtor/creditor details, merchant information, and card instruments.

---

# Get Customer (Natural Person) (/data-holder/api-reference/latam-colombia/coGetCustomerPN)

Returns personal information for a natural person (persona natural) customer, including identity details (Cédula de Ciudadanía), contact information, address, occupation, income range, PEP status, and KYC status.

---

# List products (/data-holder/platform-api/listProducts)

List products for a team

---

# Create a new product (/data-holder/platform-api/createProduct)

Create a new banking product with the provided details

---

# Get a product (/data-holder/platform-api/getProduct)

Get a product by ID

---

# Delete a product (/data-holder/platform-api/deleteProduct)

Delete a product by ID

---

# Update a product (/data-holder/platform-api/updateProduct)

Update a product by ID

---

# List consents (/data-holder/platform-api/listConsents)

List consents for a team

---

# Search Customers by email (/data-holder/api-reference/bring-your-own-data/customerSearch)

Used during authentication to lookup customer data based on email address. Customers will be authenticated via OTP before data sharing is authorised.

## POST /auth/v1/customer/search

**Buscar Clientes**

Este endpoint se utiliza durante el proceso de autenticación para identificar al cliente a partir de los atributos definidos por la entidad financiera (por ejemplo, correo electrónico, nombre de usuario u otros identificadores).

La autenticación del cliente se realiza posteriormente mediante los mecanismos de seguridad definidos por la entidad, como Strong Customer Authentication (SCA), OTP u otros métodos equivalentes, antes de autorizar el intercambio de datos.

### Request Body

**Content-Type:** `application/json`

### Responses

**200:** Respuesta correcta

| Field | Type | Description |
|-------|------|-------------|
| `data` | object[] |  |

### Example Request
```bash
curl -X POST "https://api.fiskil.com/auth/v1/customer/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

---

# Fetch a customer's identity details (/data-holder/api-reference/bring-your-own-data/getIdentity)

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


## GET /auth/v1/customer/{customerId}

**Obtener datos de identidad del cliente**

Get detailed information about a customers identity. This is used to construct ID
tokens. Data in the response will only be shared to clients if the client requested
the appropriate claim or scope. For details on how the values are used by clients,
refer to the Open ID Connect [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1)


### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Map of identifying details for the customer

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | ID of the customer.
 |
| `email` | string | The customer's contact email address |
| `emailVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the email |
| `familyName` | string | The customer's family name |
| `givenName` | string | The customer's given name (or names) |
| `name` | string | A descriptive name for the customer that is suitable for display in user interfaces |
| `phoneNumber` | string | Customer's preferred telephone number in E.164 format e.g. +614123456789. For details of the E.164 format see https://www.itu.int/rec/T-REC-E.164/en. |
| `phoneNumberVerified` | boolean | A flag indicating that some verification has been done to prove the customer owns the phone number |
| `updatedAt` | string | An RFC3339 timestamp for when the customer information was most recently set |
| `address` | object | The customer's physical address. Return only as much information as you have available. Refer to the [Open ID address claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details on each field.
 |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

# List accounts available for sharing (/data-holder/api-reference/bring-your-own-data/listAccountsAuth)

Lists all accounts belonging to the customer that are available for sharing. If account selection is supported for your Data Provider, this API will be used to present the user with a list of accounts to authorize

## GET /auth/v1/customer/{customerId}/accounts

**Listar cuentas disponibles para compartir**

Enumera todas las cuentas del cliente disponibles para compartir. Si su proveedor de datos admite la selección de cuentas, esta API se utilizará para mostrar al usuario una lista de cuentas a autorizar.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `` |  | object | No |  |

### Responses

**200:** Lista de cuentas

| Field | Type | Description |
|-------|------|-------------|
| `accounts` | object[] | Arreglo de cuentas disponibles para el consentimiento |

**401:** 

**403:** 

**404:** 

### Example Request
```bash
curl -X GET "https://api.fiskil.com/auth/v1/customer/{customerId}/accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"
```