Consumer Data Right (Energy) Register Data Holder discovery API

openapi: 3.2.0
info:
  contact:
    email: contact@dsb.gov.au
    name: Data Standards Body
    url: https://dsb.gov.au/
  description: Specifications for Register endpoints made available to participants.
  title: CDR Register Register Data Holder discovery API
  version: 1.36.0
servers:
- description: Production TLS
  url: https://api.cdr.gov.au
tags:
- description: Register Data Holder discovery endpoints
  name: Register Data Holder discovery
  x-shortName: Data Holder discovery
paths:
  /cdr-register/v1/{industry}/data-holders/brands:
    get:
      description: 'Allows Data Recipients to discover Data Holder Brands available in the CDR ecosystem.


        Obsolete versions: [v1](includes/obsolete/get-data-holder-brands-v1.html), [v2](includes/obsolete/get-data-holder-brands-v2.html).'
      operationId: getDataHolderBrands
      parameters:
      - description: The industry the participant is retrieving data for (Banking, etc.)
        explode: false
        in: path
        name: industry
        required: true
        schema:
          $ref: '#/components/schemas/IndustryEnumV2'
        style: simple
      - description: An Authorisation Token as per **[[RFC6750]](#nref-RFC6750)**.
        explode: false
        in: header
        name: Authorization
        required: true
        schema:
          type: string
        style: simple
        x-cds-type: ExternalRef
      - description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
        explode: false
        in: header
        name: x-v
        required: true
        schema:
          type: string
        style: simple
      - description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
        explode: false
        in: header
        name: x-min-v
        required: false
        schema:
          type: string
        style: simple
      - description: Query filter returns results updated since the specified date-time.
        explode: true
        in: query
        name: updated-since
        required: false
        schema:
          type: string
        style: form
        x-cds-type: DateTimeString
      - description: Page of results to request (standard pagination).
        explode: true
        in: query
        name: page
        required: false
        schema:
          default: 1
          type: integer
        style: form
        x-cds-type: PositiveInteger
      - description: Page size to request. Default is 25 (standard pagination).
        explode: true
        in: query
        name: page-size
        required: false
        schema:
          default: 25
          type: integer
        style: form
        x-cds-type: PositiveInteger
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseRegisterDataHolderBrandListV2'
          description: Successful response
          headers:
            x-v:
              $ref: '#/components/headers/XV'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: Missing Required Header / Invalid Version / Invalid Path Parameter
        '401':
          description: Invalid Bearer Token
          headers:
            WWW-Authenticate:
              description: The Response Header Field as per **[[RFC6750]](#nref-RFC6750)**.
              explode: false
              schema:
                type: string
              style: simple
              x-cds-type: ExternalRef
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: Unsupported Version
      servers:
      - description: Production MTLS
        url: https://secure.api.cdr.gov.au
      summary: Get Data Holder Brands
      tags:
      - Register Data Holder discovery
      x-version: '3'
      x-scopes:
      - cdr-register:read
  /cdr-register/v1/{industry}/data-holders/brands/summary:
    get:
      description: 'Endpoint used by participants to discover public details of Data Holder Brands from the CDR Register.


        Obsolete versions: [v1](includes/obsolete/get-data-holder-brands-summary-v1.html).'
      operationId: getDataHolderBrandsSummary
      parameters:
      - description: The industry the participant is retrieving data for (Banking, etc.)
        explode: false
        in: path
        name: industry
        required: true
        schema:
          $ref: '#/components/schemas/IndustryEnumV2'
        style: simple
      - description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
        explode: false
        in: header
        name: x-v
        required: true
        schema:
          type: string
        style: simple
      - description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
        explode: false
        in: header
        name: x-min-v
        required: false
        schema:
          type: string
        style: simple
      - description: Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value.
        explode: false
        in: header
        name: If-None-Match
        required: false
        schema:
          type: string
        style: simple
        x-cds-type: ASCIIString
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDataHoldersBrandSummaryListV2'
          description: Successful response
          headers:
            x-v:
              $ref: '#/components/headers/XV'
            Etag:
              $ref: '#/components/headers/Etag'
        '304':
          description: Not Modified - The current representation of the target resource matches with the entity-tag provided in the _If-None-Match_ request header
          headers:
            Etag:
              $ref: '#/components/headers/Etag'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: Missing Required Header / Invalid Version / Invalid Path Parameter
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: Industry Not Found
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: Unsupported Version
      summary: Get Data Holder Brands Summary
      tags:
      - Register Data Holder discovery
      x-version: '2'
  /cdr-register/v1/{industry}/data-holders/status:
    get:
      description: 'Endpoint used by participants to discover the statuses for Data Holders from the CDR Register.


        Obsolete versions: [v1](includes/obsolete/get-data-holder-statuses-v1.html).'
      operationId: getDataHolderStatuses
      parameters:
      - description: The industry the participant is retrieving data for (Banking, etc.)
        explode: false
        in: path
        name: industry
        required: true
        schema:
          $ref: '#/components/schemas/IndustryEnumV2'
        style: simple
      - description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
        explode: false
        in: header
        name: x-v
        required: true
        schema:
          type: string
        style: simple
      - description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
        explode: false
        in: header
        name: x-min-v
        required: false
        schema:
          type: string
        style: simple
      - description: Makes the request method conditional on a recipient cache or origin server not having any current representation of the target resource with an entity-tag that does not match any of those listed in the field-value.
        explode: false
        in: header
        name: If-None-Match
        required: false
        schema:
          type: string
        style: simple
        x-cds-type: ASCIIString
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataHoldersStatusList'
          description: Successful response
          headers:
            x-v:
              $ref: '#/components/headers/XV'
            Etag:
              $ref: '#/components/headers/Etag'
        '304':
          description: Not Modified - The current representation of the target resource matches with the entity-tag provided in the _If-None-Match_ request header
          headers:
            Etag:
              $ref: '#/components/headers/Etag'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: Missing Required Header / Invalid Version / Invalid Path Parameter
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorListV2'
          description: Unsupported Version
      summary: Get Data Holder Statuses
      tags:
      - Register Data Holder discovery
      x-version: '2'
components:
  schemas:
    Links:
      properties:
        self:
          description: Fully qualified link to this API call.
          type: string
          x-cds-type: URIString
      required:
      - self
      type: object
    ErrorV2_meta:
      description: Additional data for customised error codes.
      properties:
        urn:
          description: The CDR error code URN which the application-specific error code extends. Mandatory if the error _code_ is an application-specific error rather than a standardised error code.
          type: string
      type: object
      x-conditional:
      - urn
    DataHolderBrandSummaryV2:
      properties:
        dataHolderBrandId:
          description: Unique id of the Data Holder Brand issued by the CDR Register.
          maxLength: 36
          type: string
          x-conditional: true
        interimId:
          description: Interim id of the Data Holder Brand issued by the CDR Register. This is to be used to uniquely identify the record when _dataHolderBrandId_ is not populated and is not to be reused.
          maxLength: 36
          type: string
          x-conditional: true
        brandName:
          description: The name of Data Holder Brand.
          maxLength: 200
          type: string
        brandGroup:
          description: The brand group that the consumer data sharing brand is associated with.
          maxLength: 200
          type: string
          x-cds-type: ASCIIString
        publicBaseUri:
          description: Base URI for the Data Holder's Consumer Data Standard public endpoints.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        productBaseUri:
          description: Base URI for the Data Holder's Consumer Data Standard Product Reference Data (PRD) endpoints. If `null` or not present, indicates that PRD endpoints are not available.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        logoUri:
          description: Brand logo URI.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        industries:
          description: The industries the Data Holder Brand belongs to.
          items:
            $ref: '#/components/schemas/IndustriesEnumV2'
          type: array
          uniqueItems: true
        lastUpdated:
          description: The date/time that the Data Holder Brand data was last updated in the Register.
          type: string
          x-cds-type: DateTimeString
        abn:
          description: Australian Business Number for the organisation.
          maxLength: 11
          type: string
        acn:
          description: Australian Company Number for the organisation.
          maxLength: 9
          type: string
        arbn:
          description: Australian Registered Body Number. ARBNs are issued to registrable Australian bodies and foreign companies.
          maxLength: 9
          type: string
      required:
      - brandName
      - industries
      - lastUpdated
      - logoUri
      - publicBaseUri
      type: object
    MetaPaginated:
      properties:
        totalPages:
          description: The total number of pages in the full set.
          type: integer
          x-cds-type: NaturalNumber
        totalRecords:
          description: The total number of records in the full set.
          type: integer
          x-cds-type: NaturalNumber
      required:
      - totalPages
      - totalRecords
      type: object
    ResponseRegisterDataHolderBrandListV2:
      description: Response containing a list of CDR Register Data Holder Brand objects.
      properties:
        data:
          description: Response data for the query.
          items:
            $ref: '#/components/schemas/RegisterDataHolderBrandV2'
          type: array
          uniqueItems: true
        links:
          $ref: '#/components/schemas/LinksPaginated'
        meta:
          $ref: '#/components/schemas/MetaPaginated'
      required:
      - data
      - links
      - meta
      type: object
    Meta:
      type: object
    LinksPaginated:
      properties:
        first:
          description: URI to the first page of this set. Mandatory if this response is not the first page.
          type: string
          x-cds-type: URIString
        last:
          description: URI to the last page of this set. Mandatory if this response is not the last page.
          type: string
          x-cds-type: URIString
        next:
          description: URI to the next page of this set. Mandatory if this response is not the last page.
          type: string
          x-cds-type: URIString
        prev:
          description: URI to the previous page of this set. Mandatory if this response is not the first page.
          type: string
          x-cds-type: URIString
        self:
          description: Fully qualified link to this API call.
          type: string
          x-cds-type: URIString
      required:
      - self
      type: object
    ErrorV2:
      properties:
        code:
          description: The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the _meta_ object. Otherwise, the value is the error code URN.
          type: string
        title:
          description: A short, human-readable summary of the problem that **MUST NOT** change from occurrence to occurrence of the problem represented by the error code.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        meta:
          $ref: '#/components/schemas/ErrorV2_meta'
      required:
      - code
      - detail
      - title
      type: object
      x-conditional:
      - meta
    IndustriesEnumV2:
      enum:
      - banking
      - energy
      - non-bank-lending
      - telco
      type: string
    RegisterDataHolderBrandServiceEndpointV2:
      description: Endpoints related to Data Holder Brand services.
      properties:
        version:
          description: The major version of the high level standards. This is not the version of the endpoint or the payload being requested but the version of the overall standards being applied. This version number will be "`v`" followed by the major version of the standards as a positive integer (e.g., `v1`, `v12` or `v76`).
          type: string
        publicBaseUri:
          description: Base URI for the Data Holder's Consumer Data Standard public endpoints.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        productBaseUri:
          description: Base URI for the Data Holder's Consumer Data Standard Product Reference Data (PRD) endpoints. If `null` or not present, indicates that PRD endpoints are not available.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        resourceBaseUri:
          description: Base URI for the Data Holder's Consumer Data Standard resource endpoints.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        infosecBaseUri:
          description: Base URI for the Data Holder's Consumer Data Standard information security endpoints.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        extensionBaseUri:
          description: Base URI for the Data Holder extension endpoints to the Consumer Data Standard (optional).
          maxLength: 1000
          type: string
          x-cds-type: URIString
        websiteUri:
          description: Publicly available website or web resource URI.
          maxLength: 1000
          type: string
          x-cds-type: URIString
      required:
      - infosecBaseUri
      - publicBaseUri
      - resourceBaseUri
      - version
      - websiteUri
      type: object
    ResponseDataHoldersBrandSummaryListV2:
      properties:
        data:
          description: Response data for the query.
          items:
            $ref: '#/components/schemas/DataHolderBrandSummaryV2'
          type: array
          uniqueItems: true
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - data
      - links
      - meta
      type: object
    LegalEntityDetail:
      description: The data that is common to all organisations, regardless of the type (e.g., company, trust, partnership, government).
      properties:
        legalEntityId:
          description: Unique id of the organisation issued by the CDR Register.
          maxLength: 36
          type: string
        legalEntityName:
          description: Unique legal name of the organisation.
          maxLength: 36
          type: string
        logoUri:
          description: Legal Entity logo URI.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        registrationNumber:
          description: Unique registration number (if the company is registered outside Australia).
          type: string
        registrationDate:
          description: Date of registration (if the company is registered outside Australia).
          type: string
          x-cds-type: DateString
        registeredCountry:
          description: Country of registration (if the company is registered outside Australia).
          maxLength: 100
          type: string
        abn:
          description: Australian Business Number for the organisation.
          maxLength: 11
          type: string
        acn:
          description: Australian Company Number for the organisation.
          maxLength: 9
          type: string
        arbn:
          description: Australian Registered Body Number. ARBNs are issued to registrable Australian bodies and foreign companies.
          maxLength: 9
          type: string
        anzsicDivision:
          description: ANZSIC division of the organisation. **[[ANZSIC-2006]](#iref-ANZSIC-2006)**.
          maxLength: 100
          type: string
          x-cds-type: ExternalRef
        organisationType:
          description: Legal organisation type.
          enum:
          - SOLE_TRADER
          - COMPANY
          - PARTNERSHIP
          - TRUST
          - GOVERNMENT_ENTITY
          - OTHER
          type: string
        status:
          enum:
          - ACTIVE
          - REMOVED
          type: string
      required:
      - legalEntityId
      - legalEntityName
      - logoUri
      - status
      type: object
    RegisterDataHolderAuth:
      description: Defines the mechanism used and associated endpoints for Data Holder to Data Recipient authentication.
      properties:
        registerUType:
          description: The type of authentication and authorisation mechanism in use.
          enum:
          - SIGNED-JWT
          type: string
        jwksEndpoint:
          description: JWKS endpoint used for authentication by the Data Holder with the Data Recipient.
          maxLength: 1000
          type: string
          x-cds-type: URIString
      required:
      - jwksEndpoint
      - registerUType
      type: object
    IndustryEnumV2:
      enum:
      - banking
      - energy
      - non-bank-lending
      - telco
      - all
      type: string
    DataHoldersStatusList:
      properties:
        data:
          description: Response data for the query.
          items:
            $ref: '#/components/schemas/DataHolderStatus'
          type: array
          uniqueItems: true
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - data
      - links
      - meta
      type: object
    DataHolderStatus:
      properties:
        legalEntityId:
          description: Unique id of the Data Holder Legal Entity issued by the CDR Register.
          maxLength: 36
          type: string
        status:
          description: Data Holder status in the CDR Register.
          enum:
          - ACTIVE
          - REMOVED
          type: string
      required:
      - legalEntityId
      - status
      type: object
    ResponseErrorListV2:
      properties:
        errors:
          description: List of errors.
          items:
            $ref: '#/components/schemas/ErrorV2'
          type: array
      required:
      - errors
      type: object
    RegisterDataHolderBrandV2:
      properties:
        dataHolderBrandId:
          description: Unique id of the Data Holder Brand issued by the CDR Register.
          maxLength: 36
          type: string
        brandName:
          description: The name of Data Holder Brand.
          maxLength: 200
          type: string
        brandGroup:
          description: The brand group that the consumer data sharing brand is associated with.
          maxLength: 200
          type: string
          x-cds-type: ASCIIString
        industries:
          description: The industries the Data Holder Brand belongs to.
          items:
            $ref: '#/components/schemas/IndustriesEnumV2'
          type: array
          uniqueItems: true
        logoUri:
          description: Brand logo URI.
          maxLength: 1000
          type: string
          x-cds-type: URIString
        legalEntity:
          $ref: '#/components/schemas/LegalEntityDetail'
        status:
          enum:
          - ACTIVE
          - INACTIVE
          - REMOVED
          type: string
        endpointDetail:
          $ref: '#/components/schemas/RegisterDataHolderBrandServiceEndpointV2'
        authDetails:
          items:
            $ref: '#/components/schemas/RegisterDataHolderAuth'
          type: array
          uniqueItems: true
        lastUpdated:
          description: The date/time that the Data Holder Brand data was last updated in the Register.
          type: string
          x-cds-type: DateTimeString
      required:
      - authDetails
      - brandName
      - dataHolderBrandId
      - endpointDetail
      - industries
      - lastUpdated
      - legalEntity
      - logoUri
      - status
      type: object
  headers:
    Etag:
      description: Entity tag that uniquely represents the requested resource.
      explode: false
      schema:
        type: string
      style: simple
      x-cds-type: ASCIIString
    XV:
      description: The [payload version](#response-headers) that the endpoint has responded with.
      explode: false
      required: true
      schema:
        type: string
      style: simple