Ready. The design is ready for participants to use.
\nParticipants use these APIs to manage Meter Exemptions in MSATS.
\nThis documentation explains the standards, rules, context, conventions, parameters, and methods for the API endpoints.
\nThe primary audience is implementers and maintainers of APIs in participant organisations.
\nThe secondary audience is BAs and other interested parties.
\nAPI and JSON or YAML basics
\nBefore you can use the Meter Exemptions API you must:
\nHave a Participant ID with an effective date of registration. If your company is a Registered Participant, it is set up during the registration process.
\nHave a user ID and password with access rights provided by your company's participant administrator. For details, see user rights access section.
\nHave an API gateway and a TLS certificate. Participant Users require access rights to create or view API or web meter exemptions
\nTest your submission in the pre-production environment before submitting to production. AEMO encourages participants to use the pre-production environment to test procedures and train staff.
\nThe default API response is JSON but you can request a csv payload from GET requests.
\nDepending on the Accept header value, the response returns in one of the following formats:
\napplication/json: JSON schema
\ntext/csv: csv payload.
\nexemptionList: Query parameters
\nexemptionDetails: Query parameters
\nsubmitExemption: Query and Path parameters
\nProduction: {Base URL}/NEMRetail/v1/meterExemption
\nPre-production: {Base URL}/NEMRetail/v1/meterExemption
\nSee AEMO API Reference > About API > URL format for the {Base URL}.
\nProduction: {Base URL}/NEMRetail/v1/meterExemption
\nPre-production: {Base URL}/NEMRetail/v1/meterExemption
\nSee AEMO API Reference > About API > URL format for the {Base URL}.
\nMeter Exemption Guideline Supplement to the Exemption Procedure
\nAPI Reference which provides an overview of AEMO's APIs
\nGuide to Metering Exemptions (this guide is currently under development)
\nParticipant administrators provide access to the Metering Exemptions API using the following interactive entities:
\nexemptionList: Web Service Get Meter Exemption List
\nexemptionDetails: Web Service Get Meter Exemption
\nsubmitExemption: Web Service Submit Meter Exemption
\nParticipant users provide the base-64 encoded URM credentials provided by their participant administrator in the Basic Auth header.
\nAEMO APIs support HTTP protocol compression controlled by the HTTP request header attributes, allowing compression before sending and responding.
\nNote: The following applies only to the payload.
\nTo control traffic, AEMO throttles some API requests. If Participant ID requests exceed the throttling limit, the API returns a 429 or 422 response. For more details, see Response codes.
\nCode | Description | Scenario |
|---|---|---|
200 | OK | The request is processed The data payload is included |
400 | Missing required header | A required field is missing from the request header. See Header parameters |
400 | Invalid header | An invalid field is provided in the request header. Either an unexpected field is included in the request or the value provided is improperly formed. See Header parameters |
400 | Invalid page size | The page size provided is non-numeric or greater than the maximum allowed page size. See Query parameters |
400 | Invalid version | An invalid version is requested. See Header parameters |
413 | Payload Too Large | Request payload is larger than limits defined by the server. See Submission size. |
429 | Too Many Requests | The total number of inbound API requests received within a minute have exceeded the threshold. See Throttling. |
500 | Internal server error | An unforeseen error occurred processing the request |
All other 5XX | Service unavailable | Service is unavailable |
The Metering Exemptions API automates the registration and maintenance of a Meter Exemption and associated NMIs in MSATS. See the Guide to Metering Exemptions for details.
\nThe entire submission must be valid otherwise it is rejected.
\nThe active Metering Coordinator in the NMI must match the Metering Coordinator on the exemption otherwise it is rejected.
\nThe Meter Exemptions API accepts up to 75,000 NMIs in a JSON or csv request payload.
\nValid requests receive a 200 response and submission related data.
\nIf there is an error in the submission request the API rejects the request and returns a response code with a description of the error. In this case correct the error and resubmit the request.
\nSee Guide to Metering Exemptions FAQ for details.
\nA new exemptionID is returned as a payload response when a new meter exemption is successfully created 200 OK. See submitExemption endpoint for details.
\nAny NMI with a status change is identified during the nightly MSATS batch process. When the NMI status is changes to Active, the two NMI standing data fields - Meter Malfunction Exemption Number and Meter Malfunction Exemption Expiry Date are populated. If the NMI status is changed from Active to another value, the fields' values are removed.
\nUpdates are processed in a CR5101 which notifies all relevant participants on completion.
\nIt is available in pre-production from 2 October 2023.
\nFor help with terms see:
\n\nIdentifies which Participant ID the Participant User is acting for, status: required
\n"},{"key":"Authorization","value":"{{Basic Auth}}","type":"text","description":"base64 encoded Participant User's username and password, status: required
\n"},{"key":"X-market","value":"NEM","type":"text","description":"Identifies the market, status: required, type: string, format: NEM
\n"},{"key":"X-transactionID","value":"Transaction ID","description":"Unique identifier for each request, status: optional
\n","type":"text"},{"key":"Accept","value":"application/json","description":"Identifies the content types accepted by the client, options: application/json, text/csv, multipart/form-data, status: optional, type: string
\n","type":"text"}],"body":{"mode":"formdata","formdata":[]},"url":"{{baseUrl}}/NEMRetail/v1/meterExemption/submitExemption?action={{action}}&meterExemptionId={{meter_exemption_ID}}","description":"Submits a meter exemption payload and returns a message acknowledgment.
\nA submission consists of two parts:
\nMeter Exemption details - JSON payload. Contains the meter exemption details.
\nNMI list – CSV or JSON payload. Contains a list of NMIs associated with the meter exemption request.
\nAction values for meter exemption (as per submit exemption table), status: required, type: string, format: lowercase
\n","type":"text/plain"},"key":"action","value":"{{action}}"},{"description":{"content":"The meter exemption ID the request is for, status: required if action is cancel, resolve, update, or extend
Identifies the content types accepted by the client, options: application/json (default), text/csv, status: optional, type: string
\n"},{"key":"X-initiatingParticipantID","value":"Participant ID","type":"text","description":"Identifies which Participant ID the Participant User is acting for, status: required
\n"},{"key":"Authorisation","value":"{{Basic Auth}}","type":"text","description":"base64 encoded Participant User's username and password, status: required
\n"},{"key":"X-market","value":"NEM","description":"Identifies the market, status: required, type: string, format: NEM
\n","type":"text"},{"key":"X-transactionID","value":"Transaction ID","description":"Optional. Unique identifier for each request. Used for logging.
\n","type":"text"}],"body":{"mode":"formdata","formdata":[]},"url":"{{baseUrl}}/NEMRetail/v1/meterExemption/exemptionList","description":"Gets a list of Participant ID Meter Exemptions based on the search parameters.
\nThe response format is defined in the Accept header. When the content type is:
\napplication/json, up to 1000 meter exemptions records are returned
\ntext/csv, up to 75,000 meter exemption records are returned
\nGet the meter exemption for the given ID, status: optional, type: integer, maximum 15, format: numeric
\n","type":"text/plain"},"key":"meterExemptionId","value":"123456789012345"},{"disabled":true,"description":{"content":"Get meter exemptions list from a given date, status: optional, type: date, format: YYYY-MM-DD
\n","type":"text/plain"},"key":"meterExemptionFromDate","value":"2022-08-06"},{"disabled":true,"description":{"content":"Get meter exemptions list to a given date, status: optional, type: date, format: YYYY-MM-DD
\n","type":"text/plain"},"key":"meterExemptionToDate","value":"2023-01-12"},{"disabled":true,"description":{"content":"Get an individual or multiple NMIs associated to the meter exemption, status: optional, type: char maximum 10, format: alphanumeric
\n","type":"text/plain"},"key":"NMI","value":"1234567890"},{"disabled":true,"description":{"content":"Gets a list of meter exemptions for a given status, there are two status values, one each for exemptions and NMIs, status: optional, type: string maximum 50, format: ACTIVE, APPROVED, REVIEW, MOREINFO, CANCELLED, RESOLVED, EXPIRED, REJECTED
\n","type":"text/plain"},"key":"status","value":"Status"}],"variable":[]}},"response":[{"id":"306bc40a-f107-4122-b2c3-7afc7ef59601","name":"Get meter exemptions using meterExemptionId","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text","description":"Identifies the content types accepted by the client, options:\tapplication/json (default), text/csv, status: optional, type: string"},{"key":"Accept-Encoding","value":"gzip, compress, or deflate","type":"text"},{"key":"X-initiatingParticipantID","value":"Participant ID","type":"text","description":"Identifies which Participant ID the Participant User is acting for, status: required"},{"key":"Authorization","value":"Basic Auth","type":"text","description":"base64 encoded Participant User's username and password, status: required"},{"key":"X-market","value":"NEM","description":"Identifies the market, status: required, type: string, format: NEM","type":"text"},{"key":"X-transactionID","value":"adb4g8ed0-bdf5-5574-ad41-a20d8f1b2503","description":"Unique identifier for each request, status: optional, type: string","type":"text"}],"url":{"raw":"{{baseUrl}}/NEMRetail/v1/meterExemption/exemptionList?meterExemptionId=123456789012345","host":["{{baseUrl}}"],"path":["NEMRetail","v1","meterExemption","exemptionList"],"query":[{"key":"meterExemptionId","value":"123456789012345","description":"Get the meter exemption for the given ID, status: optional, type: integer, maximum 15, format: numeric"},{"key":"meterExemptionFromDate","value":"2022-08-06","description":"Get meter exemptions list from a given date, status: optional, type: date, format: YYYY-MM-DD","disabled":true},{"key":"meterExemptionToDate","value":"2023-01-12","description":"Get meter exemptions list to a given date, status: optional, type: date, format: YYYY-MM-DD","disabled":true},{"key":"NMI","value":"1234567890","description":"Get an individual or multiple NMIs associated to the meter exemption, status: optional, type: char maximum 10, format: alphanumeric","disabled":true},{"key":"status","value":"Status","description":"Gets a list of meter exemptions for a given status, there are two status values, one each for exemptions and NMIs, status: optional, type: string maximum 50, format: ACTIVE, APPROVED, REVIEW, MOREINFO, CANCELLED, RESOLVED, EXPIRED, REJECTED","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"transactionId\": \"adb4g8ed0-bdf5-5574-ad41-a20d8f1b2503\",\n \"data\": {\n \"meterExemptions\": [\n {\n \"meterExemptionId\": \"123456789012345\",\n \"exemptionDate\": \"2023-09-04\",\n \"createDate\": \"2023-10-16\",\n \"age\": \"0\",\n \"endDate\": \"2026-08-11\",\n \"status\": \"REJECTED\",\n \"nmiQuantity\": \"3\",\n \"participantId\": \"MYMC\"\n }\n ]\n }\n}"},{"id":"25a13127-2de4-44bc-9fd9-e866b3c64104","name":"Get meter exemptions using meterExemptionId CSV","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"text/csv","type":"text","description":"Identifies the content types accepted by the client, options:\tapplication/json (default), text/csv, status: optional, type: string"},{"key":"Accept-Encoding","value":"gzip, compress, or deflate","type":"text"},{"key":"X-initiatingParticipantID","value":"Participant ID","type":"text","description":"Identifies which Participant ID the Participant User is acting for, status: required"},{"key":"Authorization","value":"Basic Auth","type":"text","description":"base64 encoded Participant User's username and password, status: required"},{"key":"X-market","value":"NEM","description":"Identifies the market, status: required, type: string, format: NEM","type":"text"},{"key":"X-transactionID","value":"","description":"Unique identifier for each request, status: optional, type: string","type":"text"}],"url":{"raw":"{{baseUrl}}/NEMRetail/v1/meterExemption/exemptionList?meterExemptionId=123456789012345","host":["{{baseUrl}}"],"path":["NEMRetail","v1","meterExemption","exemptionList"],"query":[{"key":"meterExemptionId","value":"123456789012345","description":"Get the meter exemption for the given ID, status: optional, type: integer, maximum 15, format: numeric"},{"key":"meterExemptionFromDate","value":"2023-07-01","description":"Get meter exemptions list from a given date, status: optional, type: date, format: YYYY-MM-DD","disabled":true},{"key":"meterExemptionToDate","value":"2023-07-31","description":"Get meter exemptions list to a given date, status: optional, type: date, format: YYYY-MM-DD","disabled":true},{"key":"NMI","value":"2001000734","description":"Get an individual or multiple NMIs associated to the meter exemption, status: optional, type: char maximum 10, format: alphanumeric","disabled":true},{"key":"status","value":"MOREINFO","description":"Gets a list of meter exemptions for a given status, there are two status values, one each for exemptions and NMIs, status: optional, type: string maximum 50, format: ACTIVE, APPROVED, REVIEW, MOREINFO, CANCELLED, RESOLVED, EXPIRED, REJECTED","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","value":"text/csv","description":"","type":"text","enabled":true}],"cookie":[],"responseTime":null,"body":"C,DEV,METER_EXEMPTION,NEMMO,NEMMCO,2023/07/20,08:07:29,,,,NEM,,\r\nI,MEL,METER_EXEMPTION_ID,EXEMPTION_DATE,CREATE_DATE,AGE,END_DATE,STATUS,NMI_QUANTITY,PARTICIPANTID\r\nD,MEL,NEMMCO,123456789012345,2023-07-01,2023/07/10,10,2023/09/31,FOR REVIEW,2,NEMMCO\r\nC,End of Report,4\r\n"}],"_postman_id":"5b8fe6a1-e3ef-492c-91b2-f6349abc4117"},{"name":"exemptionDetails","id":"c0ffe966-671a-440e-9aaf-c9859ff4bd2c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"Identifies the content types accepted by the client, options: application/json (default), text/csv, status: optional, type: string
\n"},{"key":"X-initiatingParticipantID","value":"Participant ID","type":"text","description":"Required. Identifies which Participant ID the Participant User is acting for.
\n"},{"warning":"This is a duplicate header and will be overridden by the Authorization header generated by Postman.","key":"Authorization","value":"{{Basic Auth}}","description":"base64 encoded Participant User's username and password, status: required
\n","type":"text"},{"key":"X-market","value":"NEM","type":"text","description":"Required. Identifies the market; set to NEM.
\n"},{"key":"X-transactionID","value":"Transaction ID","description":"Unique identifier for each request, status: optional
\n","type":"text"}],"url":"{{baseUrl}}/NEMRetail/v1/meterExemption/exemptionDetails","description":"Get meter exemption details for a specified meter exemption, such as:
\nParticipant contact details
\nMeter exemption details
\nMeter exemption history
\nMeter exemption NMI list. If the NMI is not specified:
\nIn csv format, it returns the whole NMI list.
\nIn json format, it returns up to 1000 NMIs.
\nGet the meter exemption for the given ID, status: optional, type: integer, maximum 15, format: numeric
\n","type":"text/plain"},"key":"meterExemptionId","value":"123456789012345"},{"disabled":true,"description":{"content":"Get an individual or multiple NMIs associated to the meter exemption, status: optional, type: char maximum 10, format: alphanumeric
\n","type":"text/plain"},"key":"NMI","value":"1234567890"}],"variable":[]}},"response":[{"id":"73d11e8f-2631-49c4-af3d-04712ab6a8de","name":"Get meter exemption details including NMIs using meterExemptionId","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text","description":"Identifies the content types accepted by the client, options:\tapplication/json (default), text/csv, status: optional, type: string"},{"key":"Accept-Encoding","value":"gzip, compress, or deflate","type":"text","disabled":true},{"key":"X-initiatingParticipantID","value":"Participant ID","type":"text","description":"Identifies which Participant ID the Participant User is acting for, status: required"},{"key":"Authorization","value":"Basic Auth","type":"text","description":"base64encode Participant User's username and password for the Participant ID, status: required"},{"key":"X-market","value":"NEM","description":"Identifies the market, status: required, type: string","type":"text"},{"key":"X-transactionID","value":"","description":"Unique identifier for each request, status: optional\n","type":"text","disabled":true}],"url":{"raw":"{{baseUrl}}/NEMRetail/v1/meterExemption/exemptionDetails?meterExemptionId=123456789012345","host":["{{baseUrl}}"],"path":["NEMRetail","v1","meterExemption","exemptionDetails"],"query":[{"key":"meterExemptionId","value":"123456789012345","description":"Get the meter exemption for the given ID, status: optional, type: integer, maximum 15, format: numeric"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"participantContact\": {\n \"contactName\": \"John Smith\",\n \"phoneNumber\": \"0123456789\",\n \"email\": \"john.smith@company.com\"\n },\n \"meterExemption\": {\n \"meterExemptionId\": \"123456789012345\",\n \"participantId\": \"NEMMCO\",\n \"startDate\": \"2023-07-25\",\n \"endDate\": \"2024-02-29\",\n \"status\": \"REVIEW\",\n \"statusDate\": \"2023-07-25\",\n \"exemptionDate\": \"2023-07-01\",\n \"exemptionCategory\": \"MALFUNCTION\",\n \"exemptionType\": \"DEFECTIVE\",\n \"exemptionNature\": \"ACCESS\",\n \"actionTaken\": \"Actions that were taken..\",\n \"actionReason\": \"Reason for raising exemption and other relevant information....\",\n \"extendCount\": \"0\"\n },\n \"meterExemptionHistory\": [\n {\n \"status\": \"REVIEW\",\n \"statusDate\": \"2023-07-25\"\n }\n ],\n \"meterExemptionNMIs\": [\n {\n \"NMI\": \"1234567890\",\n \"status\": \"NEW\",\n \"planDate\": \"2023-12-22\",\n \"substitutionReq\": \"N\"\n },\n {\n \"NMI\": \"1234567891\",\n \"status\": \"NEW\",\n \"planDate\": \"2023-12-22\",\n \"substitutionReq\": \"N\"\n },\n {\n \"NMI\": \"1234567892\",\n \"status\": \"NEW\",\n \"planDate\": \"2023-12-22\",\n \"substitutionReq\": \"N\"\n }\n ]\n}"},{"id":"2399af2a-2d3f-4e51-8a43-0632deb4e35c","name":"Get meter exemption details including NMIs using meterExemptionId CSV","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"text/csv","type":"text","description":"Identifies the content types accepted by the client, options:\tapplication/json (default), text/csv, status: optional, type: string"},{"key":"Accept-Encoding","value":"gzip, compress, or deflate","type":"text","disabled":true},{"key":"X-initiatingParticipantID","value":"Participant ID","type":"text","description":"Identifies which Participant ID the Participant User is acting for, status: required"},{"key":"Authorization","value":"Basic Auth","type":"text","description":"base64encode Participant User's username and password for the Participant ID, status: required"},{"key":"X-market","value":"NEM","description":"Identifies the market, status: required, type: string","type":"text"},{"key":"X-transactionID","value":"","description":"Unique identifier for each request, status: optional\n","type":"text","disabled":true},{"key":"Content-Type","name":"Content-Type","value":"application/x-www-form-urlencoded","type":"text","disabled":true}],"url":{"raw":"{{baseUrl}}/NEMRetail/v1/meterExemption/exemptionDetails?meterExemptionId=123456789012345","host":["{{baseUrl}}"],"path":["NEMRetail","v1","meterExemption","exemptionDetails"],"query":[{"key":"meterExemptionId","value":"123456789012345","description":"Get the meter exemption for the given ID, status: optional, type: integer, maximum 15, format: numeric"}]}},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[{"key":"Content-Type","name":"Content-Type","value":"text/csv","description":"","type":"text","enabled":true}],"cookie":[],"responseTime":null,"body":"C,DEV,METER_EXEMPTION_NMI,NEMMO,NEMMCO,2023/07/25,14:24:48,,,,NEM,,\r\nI,MEN,NMI,STATUS,PLAN_DATE,SUBSTITUTION_REQ,STATUS_MESSAGE\r\nD,MEN,1234567890,ACTIVE,2023/12/22,N,\r\nD,MEN,1234567891,ACTIVE,2023/12/22,N,\r\nD,MEN,1234567892,ACTIVE,2023/12/22,N,\r\nC,END OF REPORT,6"}],"_postman_id":"c0ffe966-671a-440e-9aaf-c9859ff4bd2c"}],"event":[{"listen":"prerequest","script":{"id":"45aca877-1116-463c-bd9a-8b9cd5a4c7d3","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"c4da1fda-92c4-484a-800d-edc481a78ee1","type":"text/javascript","exec":[""]}}]}