> ## Documentation Index
> Fetch the complete documentation index at: https://holder.docs.fiskil.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

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

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](/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

### 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

These endpoints are called during the user consent flow to identify customers and display their accounts.

<CardGroup cols={2}>
  <Card title="Customer Search" icon="magnifying-glass" href="/api-reference/cdr/auth-customer-search">
    Look up a customer by email address or phone number during consent initiation.
  </Card>

  <Card title="Customer Accounts" icon="list" href="/api-reference/cdr/auth-customer-accounts">
    Return a list of accounts the customer can choose to share data from.
  </Card>

  <Card title="Customer Details" icon="user" href="/api-reference/cdr/auth-customer-details">
    Provide customer identity information for the consent flow.
  </Card>
</CardGroup>

<Warning>
  These endpoints are critical for the consent flow. They must return stable customer and account identifiers that never change.
</Warning>

### 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>
  <Tab title="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 |

    See the complete [CDR Banking API Reference](/api-reference/reference-banking-cdr) for detailed specifications.
  </Tab>

  <Tab title="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 |

    See the complete [CDR Energy API Reference](/api-reference/reference-energy-cdr) for detailed specifications.
  </Tab>
</Tabs>

### API Standards & Patterns

**Authentication**

Your Resource Server must validate Bearer tokens issued by Fiskil. See [Authentication](/docs/get-started/authentication) for complete details on token validation and JWKS configuration.

```http theme={null}
Authorization: Bearer eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Error Handling**

Return standard HTTP status codes and structured error responses. See [Error Handling](/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

These technical requirements are **mandatory for CDR compliance** and critical for integration success.

<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.
</Info>

### Identity Stability

<Warning>
  **Critical Requirement:** Customer IDs and Account IDs must be permanent and stable. Changing these identifiers will break consents and violate CDR compliance.
</Warning>

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

<Tip>
  Use your system's internal primary keys or generate stable UUIDs. Avoid using account numbers or other customer-facing identifiers that might change.
</Tip>

### Performance Requirements

<Check>
  CDR mandates specific response time requirements measured at the **95th percentile** — meaning 95% of requests must respond within the specified time.
</Check>

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

<Info>
  These are mandatory CDR compliance requirements. Consistent failure to meet these thresholds will impact your regulatory standing.
</Info>

For the complete breakdown of performance requirements by endpoint, see [Non-Functional Requirements](/api-reference/cdr/cdr-nfrs).

### Availability Requirements

<Check>
  **Required Availability:** 99.5% per month (maximum 3.6 hours downtime)
</Check>

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

<Tip>
  Fiskil provides availability monitoring and alerting. Configure these tools during your initial setup to track your compliance with this requirement.
</Tip>

### Data Quality Standards

<Warning>
  You must take reasonable steps to ensure CDR data is accurate, up-to-date, and complete (CDR Privacy Safeguard 11).
</Warning>

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

<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).
</Info>

***

## Implementation Checklist

Use this checklist to track your integration progress:

<Steps>
  <Step title="Set up Resource Server infrastructure">
    Provision HTTPS endpoints accessible by Fiskil with appropriate scaling and redundancy for availability requirements.

    <Tip>
      Start with your staging environment and validate before moving to production.
    </Tip>
  </Step>

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

    <Warning>
      This is critical — unstable IDs will break active consents and cause compliance issues.
    </Warning>
  </Step>

  <Step title="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](/api-reference/cdr/errors) for specifications.
  </Step>

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

    <Tip>
      Use Fiskil's telemetry tools to track these metrics. See [Logs](/docs/telemetry/logs) and [Metrics](/docs/telemetry/metrics).
    </Tip>
  </Step>

  <Step title="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](/docs/testing/compliance-tools) for testing resources.
  </Step>

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

<CardGroup cols={2}>
  <Card title="CDR FAQs" icon="circle-question" href="/api-reference/cdr/cdr-faqs">
    Common questions about CDR implementation, compliance, and operations.
  </Card>

  <Card title="Non-Functional Requirements" icon="gauge-high" href="/api-reference/cdr/cdr-nfrs">
    Complete details on performance, availability, and traffic requirements.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/cdr/errors">
    Standard error codes and response formats for CDR Resource Servers.
  </Card>

  <Card title="Consent Flow Endpoints" icon="key" href="/api-reference/cdr/auth-customer-search">
    Detailed specifications for authentication and consent endpoints.
  </Card>

  <Card title="Testing Tools" icon="vial" href="/docs/testing/compliance-tools">
    Tools and resources for testing your CDR integration.
  </Card>

  <Card title="Getting Started Guide" icon="rocket" href="/docs/get-started/index">
    Step-by-step tutorial for your first Fiskil integration.
  </Card>
</CardGroup>

### 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?

<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.
</Info>