openapi: 3.2.0 info: contact: email: contact@dsb.gov.au name: Data Standards Body url: https://dsb.gov.au/ description: Specifications for resource endpoints applicable to data holders in the Energy sector. title: CDR Energy Electricity Service Points API version: 1.36.0 servers: - description: MTLS url: https://mtls.dh.example.com/cds-au/v1 tags: - description: Electricity Service Point endpoints name: Electricity Service Points x-shortName: Service Points paths: /energy/electricity/servicepoints: get: description: 'Obtain a list of service points owned by the customer that has authorised the current session. Other Versions: [v1](includes/obsolete/get-service-points-v1.html).' operationId: listElectricityServicePoints parameters: - description: Page of results to request (standard pagination). explode: true in: query name: page required: false schema: 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: type: integer style: form x-cds-type: PositiveInteger - 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: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction. explode: false in: header name: x-fapi-interaction-id required: false schema: type: string style: simple - description: The time when the customer last logged in to the Data Recipient Software Product as described in **[[FAPI-1.0-Baseline]](#nref-FAPI-1-0-Baseline)**. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. explode: false in: header name: x-fapi-auth-date required: false schema: type: string style: simple x-conditional: true - description: The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. explode: false in: header name: x-fapi-customer-ip-address required: false schema: type: string style: simple - description: The customer's original standard http headers [Base64](#common-field-types) encoded, including the original User-Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. explode: false in: header name: x-cds-client-headers required: false schema: type: string style: simple x-cds-type: Base64 x-conditional: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/EnergyServicePointListResponseV2' description: Successful response headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' x-v: $ref: '#/components/headers/XV' '400': content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' '406': content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' '422': content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' summary: Get Service Points tags: - Electricity Service Points x-scopes: - energy:electricity.servicepoints.basic:read x-version: '2' /energy/electricity/servicepoints/{servicePointId}: get: description: 'Obtain detailed standing information for a specific service point that is owned by the customer that has authorised the current session. Other Versions: [v1](includes/obsolete/get-service-point-detail-v1.html).' operationId: getElectricityServicePointDetail parameters: - description: The _servicePointId_ to obtain data for. _servicePointId_ values are returned by service point list endpoints. Note that it is not a _nationalMeteringId_. explode: false in: path name: servicePointId required: true schema: $ref: '#/components/schemas/EnergyServicePointId' 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: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction. explode: false in: header name: x-fapi-interaction-id required: false schema: type: string style: simple - description: The time when the customer last logged in to the Data Recipient Software Product as described in **[[FAPI-1.0-Baseline]](#nref-FAPI-1-0-Baseline)**. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. explode: false in: header name: x-fapi-auth-date required: false schema: type: string style: simple x-conditional: true - description: The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. explode: false in: header name: x-fapi-customer-ip-address required: false schema: type: string style: simple - description: The customer's original standard http headers [Base64](#common-field-types) encoded, including the original User-Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. explode: false in: header name: x-cds-client-headers required: false schema: type: string style: simple x-cds-type: Base64 x-conditional: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/EnergyServicePointDetailResponseV2' description: Successful response headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' x-v: $ref: '#/components/headers/XV' '400': content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' '404': content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' '406': content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' summary: Get Service Point Detail tags: - Electricity Service Points x-scopes: - energy:electricity.servicepoints.detail:read x-version: '2' components: schemas: EnergyServicePointV2: properties: consumerProfile: $ref: '#/components/schemas/EnergyServicePointV2_consumerProfile' isGenerator: default: false description: This flag determines whether the energy at this connection point is to be treated as consumer load or as a generating unit (this may include generator auxiliary loads). If absent defaults to `false`.
**Note:** Only applicable for scheduled or semischeduled generators, does not indicate on site generation by consumer. type: boolean jurisdictionCode: description: 'Jurisdiction code to which the service point belongs.This code defines the jurisdictional rules which apply to the service point. Note the details of enumeration values below:' enum: - ALL - ACT - NEM - NSW - QLD - SA - TAS - VIC type: string lastConsumerChangeDate: description: The date the account holder changed for the NMI. type: string x-cds-type: DateString lastUpdateDateTime: description: The date and time that the information for this service point was modified. type: string x-cds-type: DateTimeString nationalMeteringId: description: The independent ID of the service point, known in the industry as the NMI. type: string servicePointClassification: description: The classification of the service point as defined in MSATS procedures. enum: - EXTERNAL_PROFILE - GENERATOR - LARGE - SMALL - WHOLESALE - NON_CONTEST_UNMETERED_LOAD - NON_REGISTERED_EMBEDDED_GENERATOR - DISTRIBUTION_WHOLESALE type: string servicePointId: allOf: - $ref: '#/components/schemas/EnergyServicePointId' description: Unique identifier for the service point. servicePointStatus: description: 'Code used to indicate the status of the service point. Note the details for the enumeration values below:' enum: - ACTIVE - DE_ENERGISED - EXTINCT - GREENFIELD - OFF_MARKET type: string validFromDate: description: The latest start date from which the constituent data sets of this service point became valid. type: string x-cds-type: DateString required: - jurisdictionCode - lastUpdateDateTime - nationalMeteringId - servicePointClassification - servicePointId - servicePointStatus - validFromDate type: object CommonPhysicalAddress: properties: addressUType: description: The type of address object present. enum: - paf - simple type: string paf: $ref: '#/components/schemas/CommonPAFAddress' simple: $ref: '#/components/schemas/CommonSimpleAddress' required: - addressUType type: object x-conditional: - simple - paf Meta: type: object PrimaryResponseErrorListV1: properties: errors: description: List of errors. items: $ref: '#/components/schemas/PrimaryErrorV1' type: array required: - errors type: object PrimaryErrorV1_allOf: properties: isSecondaryDataHolderError: default: false description: Indicates the error was propagated from a designated secondary data holder. type: boolean type: object Links: properties: self: description: Fully qualified link that generated the current response document. type: string x-cds-type: URIString required: - self type: object EnergyServicePointDetailV2_allOf_relatedParticipants: properties: party: description: The name of the party/organisation related to this service point. type: string role: description: 'The role performed by this participant in relation to the service point. Note the details of enumeration values below: ' enum: - FRMP - LNSP - DRSP type: string required: - party - role type: object EnergyServicePointDetailV2: allOf: - $ref: '#/components/schemas/EnergyServicePointV2' - $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf' EnergyServicePointId: description: A unique identifier for an Energy service point, generated according to [CDR ID Permanence](#id-permanence) requirements. type: string x-cds-type: ASCIIString EnergyServicePointDetailV2_allOf_meters: properties: meterId: description: The meter ID uniquely identifies a meter for a given service point. It is unique in the context of the service point. It is not globally unique. type: string registers: description: Usage data registers available from the meter. This may be empty where there are no meters physically installed at the service point. items: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_registers' type: array specifications: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_specifications' required: - meterId - specifications 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 that generated the current response document. type: string x-cds-type: URIString required: - self type: object x-conditional: - first - prev - next - last EnergyServicePointDetailResponseV2: properties: data: $ref: '#/components/schemas/EnergyServicePointDetailV2' links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/Meta' required: - data - links type: object EnergyServicePointDetailV2_allOf: properties: distributionLossFactor: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_distributionLossFactor' location: allOf: - $ref: '#/components/schemas/CommonPhysicalAddress' description: Location of the servicepoint. meters: description: The meters associated with the service point. This may be empty where there are no meters physically installed at the service point. items: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_meters' type: array relatedParticipants: items: $ref: '#/components/schemas/EnergyServicePointDetailV2_allOf_relatedParticipants' type: array required: - distributionLossFactor - location - relatedParticipants EnergyServicePointDetailV2_allOf_specifications: description: Technical characteristics of the meter. properties: installationType: description: 'The metering Installation type code indicates whether the metering installation has to be manually read. Note the details of enumeration values below: ' enum: - BASIC - COMMS1 - COMMS2 - COMMS3 - COMMS4 - COMMS4C - COMMS4D - MRAM - MRIM - PROF - SAMPLE - UMCP - VICAMI - NCOLNUML type: string manufacturer: description: Free text field to identify the manufacturer of the installed meter. type: string model: description: Free text field to identify the meter manufacturer's designation for the meter model. type: string nextScheduledReadDate: description: This date is the next scheduled meter read date (NSRD) if a manual Meter Reading is required. type: string x-cds-type: DateString readType: description: 'Code to denote the method and frequency of Meter Reading. The value is formatted as follows: For example, ' type: string status: description: 'A code to denote the status of the meter. Note the details of enumeration values below: ' enum: - CURRENT - DISCONNECTED type: string required: - installationType - status type: object MetaPaginated: properties: totalPages: description: The total number of pages in the full set. See [pagination](#pagination). type: integer x-cds-type: NaturalNumber totalRecords: description: The total number of records in the full set. See [pagination](#pagination). type: integer x-cds-type: NaturalNumber required: - totalPages - totalRecords type: object CommonPAFAddress: description: Australian address formatted according to the file format defined by the [PAF file format](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf). Required if _addressUType_ is set to `paf`. properties: buildingName1: description: Building/Property name 1. type: string buildingName2: description: Building/Property name 2. type: string dpid: description: Unique identifier for an address as defined by Australia Post. Also known as Delivery Point Identifier. type: string flatUnitNumber: description: Unit number (including suffix, if applicable). type: string flatUnitType: description: Type of flat or unit for the address. type: string floorLevelNumber: description: Floor or level number (including alpha characters). type: string floorLevelType: description: Type of floor or level for the address. type: string localityName: description: Full name of locality. type: string lotNumber: description: Allotment number for the address. type: string postalDeliveryNumber: description: Postal delivery number if the address is a postal delivery type. type: integer x-cds-type: PositiveInteger postalDeliveryNumberPrefix: description: Postal delivery number prefix related to the postal delivery number. type: string postalDeliveryNumberSuffix: description: Postal delivery number suffix related to the postal delivery number. type: string postalDeliveryType: description: Postal delivery type. (e.g., PO BOX). Valid enumeration defined by Australia Post PAF code file. type: string postcode: description: Postcode for the locality. type: string state: description: State in which the address belongs. Valid enumeration defined by Australia Post PAF code file [State Type Abbreviation](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf). `NSW`, `QLD`, `VIC`, `NT`, `WA`, `SA`, `TAS`, `ACT`, `AAT`. type: string streetName: description: The name of the street. type: string streetSuffix: description: The street type suffix. Valid enumeration defined by Australia Post PAF code file. type: string streetType: description: The street type. Valid enumeration defined by Australia Post PAF code file. type: string thoroughfareNumber1: description: Thoroughfare number for a property (first number in a property ranged address). type: integer x-cds-type: PositiveInteger thoroughfareNumber1Suffix: description: Suffix for the thoroughfare number. Only relevant if _thoroughfareNumber1_ is populated. type: string thoroughfareNumber2: description: Second thoroughfare number (only used if the property has a ranged address e.g., 23-25). type: integer x-cds-type: PositiveInteger thoroughfareNumber2Suffix: description: Suffix for the second thoroughfare number. Only relevant if _thoroughfareNumber2_ is populated. type: string required: - localityName - postcode - state type: object EnergyServicePointDetailV2_allOf_registers: properties: averagedDailyLoad: description: The energy delivered through a connection point or metering point over an extended period normalised to a 'per day' basis (kWh). This value is calculated annually. type: number consumptionType: description: 'Actual/Subtractive Indicator. Note the details of enumeration values below: ' enum: - ACTUAL - CUMULATIVE type: string controlledLoad: description: Indicates whether the energy recorded by this register is created under a Controlled Load regime. type: boolean multiplier: description: Multiplier required to take a register value and turn it into a value representing billable energy. type: number networkTariffCode: description: The Network Tariff Code is a free text field containing a code supplied and published by the local network service provider. type: string registerConsumptionType: description: Indicates the consumption type of register. enum: - INTERVAL - BASIC - PROFILE_DATA - ACTIVE_IMPORT - ACTIVE - REACTIVE_IMPORT - REACTIVE type: string registerId: description: Unique identifier of the register within this service point. Is not globally unique. type: string registerSuffix: description: Register suffix of the meter register where the meter reads are obtained. type: string timeOfDay: description: Code to identify the time validity of register contents. enum: - ALLDAY - INTERVAL - PEAK - BUSINESS - SHOULDER - EVENING - OFFPEAK - CONTROLLED - DEMAND type: string unitOfMeasure: description: The unit of measure for data held in this register. type: string required: - registerConsumptionType - registerId 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 EnergyServicePointListResponseV2_data: properties: servicePoints: items: $ref: '#/components/schemas/EnergyServicePointV2' type: array required: - servicePoints type: object EnergyServicePointV2_consumerProfile: properties: classification: description: A code that defines the consumer class as defined in the National Energy Retail Regulations, or in overriding Jurisdictional instruments. enum: - BUSINESS - RESIDENTIAL type: string threshold: description: 'A code that defines the consumption threshold as defined in the National Energy Retail Regulations, or in overriding Jurisdictional instruments. Note the details of enumeration values below: ' enum: - LOW - MEDIUM - HIGH type: string type: object PrimaryErrorV1: allOf: - $ref: '#/components/schemas/PrimaryErrorV1_allOf' - $ref: '#/components/schemas/ErrorV2' 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 detail: description: A human-readable explanation specific to this occurrence of the problem. type: string meta: $ref: '#/components/schemas/ErrorV2_meta' 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 required: - code - detail - title type: object x-conditional: - meta CommonSimpleAddress: description: Required if _addressUType_ is set to `simple`. properties: addressLine1: description: First line of the standard address object. type: string addressLine2: description: Second line of the standard address object. type: string addressLine3: description: Third line of the standard address object. type: string city: description: Name of the city or locality. type: string country: default: AUS description: A valid [ISO 3166 Alpha-3](https://www.iso.org/iso-3166-country-codes.html) country code. Australia (`AUS`) is assumed if country is not present. type: string x-cds-type: ExternalRef mailingName: description: Name of the individual or business formatted for inclusion in an address used for physical mail. type: string postcode: description: Mandatory for Australian addresses. type: string state: description: Free text if the country is not Australia. If country is Australia then must be one of the values defined by the [State Type Abbreviation](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf) in the PAF file format. `NSW`, `QLD`, `VIC`, `NT`, `WA`, `SA`, `TAS`, `ACT`, `AAT`. type: string required: - addressLine1 - city - state type: object x-conditional: - postcode EnergyServicePointDetailV2_allOf_distributionLossFactor: properties: code: description: A code used to identify data loss factor for the service point values. Refer to AEMO distribution loss factor documents for each financial year to interpret. type: string description: description: Description of the data loss factor code and value. type: string lossValue: description: The value associated with the loss factor code. type: string required: - code - description - lossValue type: object EnergyServicePointListResponseV2: properties: data: $ref: '#/components/schemas/EnergyServicePointListResponseV2_data' links: $ref: '#/components/schemas/LinksPaginated' meta: $ref: '#/components/schemas/MetaPaginated' required: - data - links - meta type: object headers: XFAPIInteractionId: description: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction. explode: false required: true schema: type: string style: simple XV: description: The [payload version](#response-headers) that the endpoint has responded with. explode: false required: true schema: type: string style: simple