CONTENTS

1.0 Introduction

The SIP (Safe Isolation Provider) API service for SIP-accredited Meter Equipment Managers (MEMs), it enables installers, including Electric Vehicle (EV) charging installation companies, to send regulatory market messages following de-energisation and re-energisation processes. This version of the API is structured to closely follow the engineer's workflow as captured in the job and worksheets.

1.1 Document Purpose

This document sets out the technical details necessary for a SIP’s selected job management and field services platform to send communications to the Shocking Energy system in order to support the generation of the required industry data flows following a site visit.

Through the integration API described in this document, the SIP engineer shall be able to trigger actions within the Shocking Energy system via the SIP system, as part of defined business processes.

2.0 Message Format and Flow

Each interface operation consists of the following steps:

The SIP system makes a Request to an endpoint within the Shocking Energy system, in the form of a HTTPS POST.
The Shocking Energy system validates the Request. If the request is not accepted, the Shocking Energy system responds with error information. If the request is accepted, the Shocking Energy system responds with a message including the Scenario I.D that identifies the outcome scenario that will performed.
For accepted requests, the Shocking Energy System then converts the API data into the relevant industry data flows. These industry data flows are sent to the DTN via AWS S3 and directed to the relevant parties (Supplier, SCIF/DNO) and any applicable incoming industry flows are received by the Shocking Energy system.

Screenshot 2025-01-28 at 14.08.07.png

3.0 API Requests

3.1 Request Mechanism

Each operation is triggered by submitting a Request to the Shocking Energy endpoint that accepts a JSON body object composed of various blocks that correspond to the sections in the engineer's worksheet.

If the request is valid, the Shocking Energy system will respond with an HTTPS 200 status code and a JSON model containing a status, message, request I.D and scenario.

If the request is invalid, the Shocking Energy will return an HTTPS 4xx or 5xx status code indicating the issue. HTTPS 400 status codes return a JSON model that provides additional details about the error.

3.2 Security

HTTPS requests to the Shocking Energy system must be made securely, the message security is through API key-based authentication. Each request must include a valid API key in the request headers to authenticate the client. This API key serves as a unique identifier for the client and must be kept secure to prevent unauthorised access. Any request without a valid API key, or with an incorrect key, will be rejected.

3.3 Endpoint

All requests should be sent via HTTPS POST to https://api.shocking.energy/v4/sip

3.4 Request Headers

Content-Type: application/json
Authorization: Bearer $SE_API_KEY

3.5 Rate Limits

Standard Rate Limit: 1000 requests per hour
Burst Rate Limit: 100 requests per minute

If the rate limit is exceeded, the API will return a 429 status code Too Many Requests response.

3.6 Conventions

HTTPS is required for all API requests.
Property names are in snake_case.
Dates are in ISO 8601 format (YYYY-MM-DD).
Times are in 24-hour format (HH:MM).
Boolean values should be sent as true or false.
The API does not support empty strings or null values.
Photos should be encoded as base64 strings.

4.0 API Structure

4.1 Request Body

The request body is a JSON object composed of various blocks that correspond to the sections in the engineer's worksheet. Here's an overview of the available blocks:

Block Name	Description	Required
job_details	Job details for the request	Yes
customer_contact	Customer contact outputs from the job.	Yes
risk_assessment	Risk assessment outputs from the job.	Yes*
Required if customer_contact.prevented_to_proceed is No
meter	The information on the meter that is on site	Yes*
Required if risk_assessment.meter_access_clear is true
site_safety	Site safety outputs from the job.	Yes*
Required if one of risk_assessment.site_energised or risk_assessment_energisation_only_job is true
job_execution	Job execution outcomes from the job.	Yes*
Required if site_safety.can_continue is true
job_completion	The outcome of the job.	Yes

4.2 Block Definitions

4.2.1 job_details

API Field	Type	Description	Required
job_id	string	Unique ID of the job.	Yes
mpan	string	MPAN of the premise.	Yes
supplier_mpid	string	MPID of the supplier.	Yes
contact_name	string	The name of the person on site.	Yes
address	string	The flat/name number, house name/number and street of the premise	Yes
town	string	The town of the premise.	Yes
post_code	string	The postcode of the premise	Yes
contact_telephone	string	The telephone number for the customer at the premise.	Yes
customer_vulnerability	string	Any pre-existing customer vulnerabilities at the premise.	No
site_risk	string	Any pre-existing site risks at the premise.	No

Example:

  "job_details": {
    "job_id": "87d00eff-42b5-40a6-bf69-abcb66f054ff",
    "mpan": "1129383838383",
    "supplier_mpid": "TEST",
    "contact_name": "Mr Bob Smith",
    "address": "Flat 1, 25 Spear Building, High Street",
    "town": "Coventry",
    "post_code": "CV5 4DD"
    "contact_telephone": "07737374773",
    "customer_vulnerability": "Children over 5",
    "site_risk": "Verbally abusive"
  }

4.2.2 customer_contact

API Field	Type	Description	Required
contact_made	boolean	Whether the engineer was able to make contact with the customer.	Yes
call_outcome	string
(enum)	The outcome of the call attempt. One of:

Customer confirmed
Invalid phone number
N/A(voicemail left)
N/A(no voicemail left)
Not convenient | Yes* Required if contact_made is true | | arrived_on_site | boolean | Whether the engineer has arrived on site. | Yes | | able_to_access_property | boolean | Whether the engineer has been able to access the property. | Yes* Required if arrived_on_site is true | | critical_medical_equipment | boolean | Whether there is any critical medical equipment(s) that are reliant on the electricity supply. | Yes* Required if able_to_access_property is true | | critical_medical_equipment_info | string | Any notes regarding the critical medical equipment(s). | Yes* Required if critical_medical_equipment is true | | third_party_presence | boolean | Whether there is any third party presence required. | Yes* Required if able_to_access_property is true | | third_party_presence_info | string | Any notes regarding the third party presence required. | Yes* Required if third_party_presence is true | | prevented_to_proceed | string (enum) | Whether the engineer is able to proceed based on the outputs for critical medical equipment(s) and third party presence required questions. One of:
No
Critical Medical Equipment
Lack of Third-Party
Critical Medical Equipment & Lack of Third-Party | Yes* Required if able_to_access_property is true |

Example:

  "customer_contact": {
    "contact_made": true,
    "call_outcome": "Customer confirmed",
    "arrived_on_site": true,
    "able_to_access_property": true,
    "critical_medical_equipment": true,
    "critical_medical_equipment_info": "Feeding machine.",
    "third_party_presence": true,
    "third_party_presence_info": "Carer required to be on site.",
    "prevented_to_proceed": "Critical Medical Equipment"
  }

4.2.3 risk_assessment

| --- | --- | --- | --- |

Example:

  "risk_assessment": {
    "engineer_competent": true,
    "suitable_environment": true,
    "suitable_heights": true,
    "site_risk_list": ["No risk identified"],
    "safe_to_continue": true,
    "meter_access_clear": true,
    "site_energised": false,
    "energisation_only_job": true
  }

4.2.4 meter

| --- | --- | --- | --- |

Example:

  "meter": {
    "serial_number": "L1282738282",
    "location": "A",
    "reading_available": "Yes",
    "no_of_rates": "09",
    "number_of_dials": 5,
    "rate_1_reading": "28933",
    "rate_2_reading": "28933",
    "rate_3_reading": "28933",
    "rate_4_reading": "28933",
    "rate_5_reading": "28933",
    "rate_6_reading": "28933",
    "rate_7_reading": "28933",
    "rate_8_reading": "28933",
    "rate_9_reading": "28933",
    "smart_meter": true,
    "comms_state": "Flashing every 5 seconds",
    "photo": "base64_encoded_photo_data"
  }

4.2.5 site_safety

| --- | --- | --- | --- | --- |

Example:

  "site_safety": {
    "polarity_test_passed": true,
    "dno_issue": "B",
    "dno_code_a": "A05",
    "dno_code_b": "B01",
    "dno_code_c": "C02",
    "dno_comment": "DNO issue on site.",
    "metering_equipment_issues": "22",
    "meter_issue_comment": "Metering issue on site.",
    "tampering_code": "15",
    "tamper_comment": "Metering issue on site.",
    "consumer_issue": true,
    "consumer_issue_type": "Category EA issues",
    "can_continue": true
  }

4.2.6 job_execution

| --- | --- | --- | --- |

Example:

  "job_execution": {
    "pre_job_photo": "base64_encoded_photo_data",
    "action_required": "Install Isolator",
    "site_de_energised": true,
    "de_energisation_time": "2025-01-08T12:05:00.000Z",
    "site_re_energised": true,
    "re_energisation_time": "2025-01-08T12:05:00.000Z",
    "fuse_resealed": true,
    "post_resealing_photo": "base64_encoded_photo_data",
    "isolator_fitted": false,
    "isolator_failure_reason": "Damaged initial isolator, no spare on van.",
    "meter_tails_upgraded": true,
    "meter_tails_supplier": "Own company",
    "polarity_test_passed": true,
    "comms_state": "Flashing every 5 seconds",
    "post_job_photo": "base64_encoded_photo_data"
  }

4.2.7 job_completion

| --- | --- | --- | --- |

Example:

  "job_completion": {
    "outcome": "Aborted",
    "date_of_action": "2025-01-28",
    "abort_category": "Supply Issues",
    "abort_engineer_risk_equipment": "52",
    "abort_meter_equipment": "39",
    "abort_access": "20",
    "abort_safety": "23",
    "abort_supply": "04",
    "abort_tampering": "11",
    "notices_issued": "Not Applicable",
    "job_notes": "Job aborted, supply issues"
  }