openapi: 3.2.0 info: title: CDR Energy Electricity Service Points API version: 1.36.0 description: Specifications for resource endpoints applicable to data holders in the Energy sector. contact: name: Data Standards Body email: contact@dsb.gov.au url: https://dsb.gov.au/ servers: - description: MTLS url: https://mtls.dh.example.com/cds-au/v1 tags: - name: Electricity Service Points x-shortName: Service Points description: Electricity Service Point endpoints paths: /energy/electricity/servicepoints: get: summary: Get Service Points 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 x-scopes: - energy:electricity.servicepoints.basic:read tags: - Electricity Service Points x-version: '2' parameters: - $ref: '#/components/parameters/QueryPage' - $ref: '#/components/parameters/QueryPageSize' - $ref: '#/components/parameters/HeaderXV' - $ref: '#/components/parameters/HeaderXMinV' - $ref: '#/components/parameters/HeaderXFAPIInteractionId' - $ref: '#/components/parameters/HeaderXFAPIAuthDate' - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress' - $ref: '#/components/parameters/HeaderXCDSClientHeaders' responses: '200': $ref: '#/components/responses/ListElectricityServicePoints200' '400': $ref: '#/components/responses/ListElectricityServicePoints400' '406': $ref: '#/components/responses/ListElectricityServicePoints406' '422': $ref: '#/components/responses/ListElectricityServicePoints422' /energy/electricity/servicepoints/{servicePointId}: get: summary: Get Service Point Detail operationId: getElectricityServicePointDetail x-scopes: - energy:electricity.servicepoints.detail:read 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).' tags: - Electricity Service Points x-version: '2' parameters: - $ref: '#/components/parameters/PathServicePointId' - $ref: '#/components/parameters/HeaderXV' - $ref: '#/components/parameters/HeaderXMinV' - $ref: '#/components/parameters/HeaderXFAPIInteractionId' - $ref: '#/components/parameters/HeaderXFAPIAuthDate' - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress' - $ref: '#/components/parameters/HeaderXCDSClientHeaders' responses: '200': $ref: '#/components/responses/GetElectricityServicePointDetail200' '400': $ref: '#/components/responses/GetElectricityServicePointDetail400' '404': $ref: '#/components/responses/GetElectricityServicePointDetail404' '406': $ref: '#/components/responses/GetElectricityServicePointDetail406' components: parameters: HeaderXFAPIInteractionId: name: x-fapi-interaction-id 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. in: header schema: type: string HeaderXV: name: x-v 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). in: header required: true schema: type: string HeaderXFAPICustomerIPAddress: name: x-fapi-customer-ip-address 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. in: header schema: type: string HeaderXCDSClientHeaders: name: x-cds-client-headers 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. in: header x-conditional: true schema: type: string x-cds-type: Base64 QueryPageSize: name: page-size description: Page size to request. Default is 25 (standard pagination). in: query schema: type: integer default: '25' x-cds-type: PositiveInteger HeaderXFAPIAuthDate: name: x-fapi-auth-date 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. in: header x-conditional: true schema: type: string PathServicePointId: name: servicePointId description: The _servicePointId_ to obtain data for. _servicePointId_ values are returned by service point list endpoints. Note that it is not a _nationalMeteringId_. in: path required: true schema: $ref: '#/components/schemas/EnergyServicePointId' QueryPage: name: page description: Page of results to request (standard pagination). in: query schema: type: integer default: '1' x-cds-type: PositiveInteger HeaderXMinV: name: x-min-v 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`. in: header schema: type: string schemas: LinksPaginated: type: object required: - self x-conditional: - first - prev - next - last properties: self: type: string description: Fully qualified link that generated the current response document. x-cds-type: URIString first: type: string description: URI to the first page of this set. Mandatory if this response is not the first page. x-cds-type: URIString prev: type: string description: URI to the previous page of this set. Mandatory if this response is not the first page. x-cds-type: URIString next: type: string description: URI to the next page of this set. Mandatory if this response is not the last page. x-cds-type: URIString last: type: string description: URI to the last page of this set. Mandatory if this response is not the last page. x-cds-type: URIString CommonSimpleAddress: description: Required if _addressUType_ is set to `simple`. required: - addressLine1 - city - state type: object properties: mailingName: type: string description: Name of the individual or business formatted for inclusion in an address used for physical mail. addressLine1: type: string description: First line of the standard address object. addressLine2: type: string description: Second line of the standard address object. addressLine3: type: string description: Third line of the standard address object. postcode: type: string description: Mandatory for Australian addresses. city: type: string description: Name of the city or locality. state: type: string 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`. country: type: string 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. default: AUS x-cds-type: ExternalRef x-conditional: - postcode CommonPhysicalAddress: required: - addressUType type: object properties: addressUType: type: string description: The type of address object present. enum: - paf - simple simple: $ref: '#/components/schemas/CommonSimpleAddress' paf: $ref: '#/components/schemas/CommonPAFAddress' x-conditional: - simple - paf Meta: type: object EnergyServicePointId: type: string description: A unique identifier for an Energy service point, generated according to [CDR ID Permanence](#id-permanence) requirements. x-cds-type: ASCIIString EnergyServicePointListResponseV2: type: object required: - data - links - meta properties: data: type: object required: - servicePoints properties: servicePoints: type: array items: $ref: '#/components/schemas/EnergyServicePointV2' links: $ref: '#/components/schemas/LinksPaginated' meta: $ref: '#/components/schemas/MetaPaginated' EnergyServicePointV2: type: object required: - servicePointId - nationalMeteringId - servicePointClassification - servicePointStatus - jurisdictionCode - validFromDate - lastUpdateDateTime properties: servicePointId: description: Unique identifier for the service point. allOf: - $ref: '#/components/schemas/EnergyServicePointId' nationalMeteringId: type: string description: The independent ID of the service point, known in the industry as the NMI. servicePointClassification: type: string 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 servicePointStatus: type: string 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 jurisdictionCode: type: string 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 isGenerator: type: boolean 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. default: false validFromDate: type: string x-cds-type: DateString description: The latest start date from which the constituent data sets of this service point became valid. lastUpdateDateTime: type: string x-cds-type: DateTimeString description: The date and time that the information for this service point was modified. lastConsumerChangeDate: type: string x-cds-type: DateString description: The date the account holder changed for the NMI. consumerProfile: type: object properties: classification: type: string description: A code that defines the consumer class as defined in the National Energy Retail Regulations, or in overriding Jurisdictional instruments. enum: - BUSINESS - RESIDENTIAL 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 PrimaryResponseErrorListV1: type: object required: - errors properties: errors: description: List of errors. type: array items: $ref: '#/components/schemas/PrimaryErrorV1' MetaPaginated: type: object required: - totalPages - totalRecords properties: totalRecords: type: integer description: The total number of records in the full set. See [pagination](#pagination). x-cds-type: NaturalNumber totalPages: type: integer description: The total number of pages in the full set. See [pagination](#pagination). x-cds-type: NaturalNumber 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`. required: - localityName - postcode - state type: object properties: dpid: type: string description: Unique identifier for an address as defined by Australia Post. Also known as Delivery Point Identifier. thoroughfareNumber1: type: integer description: Thoroughfare number for a property (first number in a property ranged address). x-cds-type: PositiveInteger thoroughfareNumber1Suffix: type: string description: Suffix for the thoroughfare number. Only relevant if _thoroughfareNumber1_ is populated. thoroughfareNumber2: type: integer description: Second thoroughfare number (only used if the property has a ranged address e.g., 23-25). x-cds-type: PositiveInteger thoroughfareNumber2Suffix: type: string description: Suffix for the second thoroughfare number. Only relevant if _thoroughfareNumber2_ is populated. flatUnitType: type: string description: Type of flat or unit for the address. flatUnitNumber: type: string description: Unit number (including suffix, if applicable). floorLevelType: type: string description: Type of floor or level for the address. floorLevelNumber: type: string description: Floor or level number (including alpha characters). lotNumber: type: string description: Allotment number for the address. buildingName1: type: string description: Building/Property name 1. buildingName2: type: string description: Building/Property name 2. streetName: type: string description: The name of the street. streetType: type: string description: The street type. Valid enumeration defined by Australia Post PAF code file. streetSuffix: type: string description: The street type suffix. Valid enumeration defined by Australia Post PAF code file. postalDeliveryType: type: string description: Postal delivery type. (e.g., PO BOX). Valid enumeration defined by Australia Post PAF code file. postalDeliveryNumber: type: integer description: Postal delivery number if the address is a postal delivery type. x-cds-type: PositiveInteger postalDeliveryNumberPrefix: type: string description: Postal delivery number prefix related to the postal delivery number. postalDeliveryNumberSuffix: type: string description: Postal delivery number suffix related to the postal delivery number. localityName: type: string description: Full name of locality. postcode: type: string description: Postcode for the locality. state: type: string 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`. Links: type: object required: - self properties: self: type: string description: Fully qualified link that generated the current response document. x-cds-type: URIString PrimaryErrorV1: type: object allOf: - type: object properties: isSecondaryDataHolderError: type: boolean description: Indicates the error was propagated from a designated secondary data holder. default: false - $ref: '#/components/schemas/ErrorV2' ErrorV2: type: object required: - code - title - detail x-conditional: - meta properties: code: type: string 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. title: type: string 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. detail: type: string description: A human-readable explanation specific to this occurrence of the problem. meta: type: object x-conditional: - urn description: Additional data for customised error codes. properties: urn: type: string 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. EnergyServicePointDetailResponseV2: type: object required: - data - links properties: data: $ref: '#/components/schemas/EnergyServicePointDetailV2' links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/Meta' EnergyServicePointDetailV2: allOf: - $ref: '#/components/schemas/EnergyServicePointV2' - required: - distributionLossFactor - relatedParticipants - location properties: distributionLossFactor: type: object required: - code - description - lossValue properties: code: type: string 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. description: type: string description: Description of the data loss factor code and value. lossValue: type: string description: The value associated with the loss factor code. relatedParticipants: type: array items: type: object required: - party - role properties: party: type: string description: The name of the party/organisation related to this service point. role: type: string description: 'The role performed by this participant in relation to the service point. Note the details of enumeration values below: ' enum: - FRMP - LNSP - DRSP location: description: Location of the servicepoint. allOf: - $ref: '#/components/schemas/CommonPhysicalAddress' meters: description: The meters associated with the service point. This may be empty where there are no meters physically installed at the service point. type: array items: type: object required: - meterId - specifications properties: meterId: type: string 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. specifications: type: object description: Technical characteristics of the meter. required: - status - installationType properties: status: type: string description: 'A code to denote the status of the meter. Note the details of enumeration values below: ' enum: - CURRENT - DISCONNECTED installationType: type: string 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 manufacturer: type: string description: Free text field to identify the manufacturer of the installed meter. model: type: string description: Free text field to identify the meter manufacturer's designation for the meter model. readType: type: string description: 'Code to denote the method and frequency of Meter Reading. The value is formatted as follows: For example, ' nextScheduledReadDate: type: string x-cds-type: DateString description: This date is the next scheduled meter read date (NSRD) if a manual Meter Reading is required. registers: description: Usage data registers available from the meter. This may be empty where there are no meters physically installed at the service point. type: array items: type: object required: - registerId - registerConsumptionType properties: registerId: type: string description: Unique identifier of the register within this service point. Is not globally unique. registerSuffix: type: string description: Register suffix of the meter register where the meter reads are obtained. averagedDailyLoad: type: number 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. registerConsumptionType: type: string description: Indicates the consumption type of register. enum: - INTERVAL - BASIC - PROFILE_DATA - ACTIVE_IMPORT - ACTIVE - REACTIVE_IMPORT - REACTIVE networkTariffCode: type: string description: The Network Tariff Code is a free text field containing a code supplied and published by the local network service provider. unitOfMeasure: type: string description: The unit of measure for data held in this register. timeOfDay: type: string description: Code to identify the time validity of register contents. enum: - ALLDAY - INTERVAL - PEAK - BUSINESS - SHOULDER - EVENING - OFFPEAK - CONTROLLED - DEMAND multiplier: type: number description: Multiplier required to take a register value and turn it into a value representing billable energy. controlledLoad: type: boolean description: Indicates whether the energy recorded by this register is created under a Controlled Load regime. consumptionType: type: string description: 'Actual/Subtractive Indicator. Note the details of enumeration values below: ' enum: - ACTUAL - CUMULATIVE headers: XV: description: The [payload version](#response-headers) that the endpoint has responded with. required: true schema: type: string 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. required: true schema: type: string responses: GetElectricityServicePointDetail404: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityServicePoints422: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityServicePoints400: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityServicePoints406: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' GetElectricityServicePointDetail200: description: Successful response headers: x-v: $ref: '#/components/headers/XV' x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/EnergyServicePointDetailResponseV2' ListElectricityServicePoints200: description: Successful response headers: x-v: $ref: '#/components/headers/XV' x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/EnergyServicePointListResponseV2' GetElectricityServicePointDetail400: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' GetElectricityServicePointDetail406: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1'