Oracle Utilities REST API for Digital Self Service Energy Management

https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/
Admin
A REST API platform that enables utility companies to create personalized web and mobile experiences...
Tokens:190,973
Snippets:669
Trust Score:9.7
Update:10 months ago
Show doc for...
Tokens:
Raw
### Customer Example Response (JSON)

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-customer-data-v2-utilitycode-customers-get

Provides an example of the JSON structure for a successful customer response. This illustrates the format and typical values for customer data.

```json
{
    "response":{
        "id":1071,
        "name":"David Bowie",
        "recipient":"RECIPIENT",
        "utilityCustomerId":"1872099045-387109999",
        "utilityInternalId":"1872099045",
        "utilityInternalId2":"18720-99045"
    }
}
```

--------------------------------

### Example OpenEngagement Object

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-customer-engagement-v1-utilities-utilitycode-engagements-opens-get

An example of an 'OpenEngagement' object, illustrating the data structure and typical values for engagement events.

```json
{
    "id":"accf6a68-66c8-11e9-a923-1681be663d3e",
    "product":"HER",
    "communicationEventType":"HOME_ENERGY",
    "eventType":"OPEN",
    "trackId":"accf6cf2-66c8-11e9-a923-1681be663d3e",
    "campaignId":"accf6f22-66c8-11e9-a923-1681be663d3e",
    "moduleId":"accf7256-66c8-11e9-a923-1681be663d3e",
    "emailAddress":"86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d",
    "occurredOn":"2018-02-19T13:01:00Z",
    "utilityCustomerId":"1872099045-387109999",
    "utilityInternalId":1872099045,
    "utilityInternalId2":"18720-99045",
    "customerMultitenantId":"util-1872099045-387109999",
    "communicationMultitenantId":"util-8-e89ade"
}
```

--------------------------------

### Install cURL on Windows

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/UsingcURL

Instructions for installing cURL on a Windows system, including downloading the executable, obtaining SSL certificates, setting the CURL_CA_BUNDLE environment variable for SSL CA verification.

```shell
C:\curl> set CURL_CA_BUNDLE=ca-bundle.crt
```

--------------------------------

### Get Always-On Usage Data Example Response (JSON)

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-disaggregation-v1-utilities-utilitycode-customers-customerid-consumption-alwayson-get

Provides an example of a JSON response when requesting always-on energy usage data. This example demonstrates the expected format and data types for the 'value', 'ratio', 'startDate', and 'endDate' fields.

```json
{
    "response": {
        "ratio": 0.02,
        "value": 15,
        "startDate": "2019-02-01T00:00:00.00Z",
        "endDate": "2019-03-01T00:00:00.00Z"
    }
}
```

--------------------------------

### URL Structure and Example

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/QuickStart

This section details the structure of the REST API URLs and provides an example for retrieving utility account information.

```APIDOC
## URL Structure

You access and call the REST resources using the following URL structure:

`https://domain.com/apis/service-version/utilitycode/resource`

### Example URI

`https://cxapi.opower.com/apis/customer-data-v2/UTIL/customers/123456/utility_accounts`

Where:
* `domain`: The host name for the REST server. Production: `cxapi.opower.com`, Stage: `cxapi-stage.opower.com`.
* `service-version`: The service name and API endpoint version.
* `utilitycode`: A three or four-letter code for your utility.
* `resource-path`: The relative path defining the resource.
```

--------------------------------

### Retrieve Customer Home Profile with cURL

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/UsingcURL

This example demonstrates how to retrieve a customer's home profile information via a cURL GET request. It specifies authorization and content type headers. The expected response is a JSON object containing home-related attributes.

```shell
curl -X GET -H "Authorization: Bearer ${BEARER}" -H "Content-Type: application/json" 'https://cxapi-stage.opower.com/apis/customer-data-v2/util/customers/1/home_profile'
```

--------------------------------

### Example Day Usage Response JSON

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Provides an example of a 'DayUsageResponse' JSON object, illustrating the expected format and data for a specific utility customer's electricity usage on a given day.

```json
{
    "utilityCode": "util",
    "utilityCustomerId": "9999990000-9999990000",
    "fuelType": "ELECTRICITY",
    "start": "2017-09-01T00:00:00-06:00",
    "end": "2017-09-01T00:30:00-06:00",
    "unit": "KWH",
    "streams": [
        {
            "utilityServicePointId": "12345001",
            "intervals": [
                {
                    "start": "2017-09-01T00:00:00-06:00",
                    "end": "2017-09-01T00:15:00-06:00",
                    "usage": 0.14,
                    "readType": "ACTUAL"
                },
                {
                    "start": "2017-09-01T00:15:00-06:00",
                    "end": "2017-09-01T00:30:00-06:00",
                    "usage": 0.19,
                    "readType": "ACTUAL"
                }
            ]
        }
    ]
}
```

--------------------------------

### 200 Response: Example Utility Accounts JSON

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-customer-data-v2-utilitycode-customers-id-utility_accounts-get

Provides an example of the JSON response body for a successful operation that returns utility accounts. This example illustrates the structure and data types of the fields within a utility account object, including ID, utilityAccountId, moveInDate, meterType, and resolution.

```json
{
    "response": {
        "id": 1071,
        "utilityAccountId": "1872099045",
        "moveInDate": "2011-10-15",
        "meterType": "ELEC",
        "resolution": "HALF_HOUR"
    }
}
```

--------------------------------

### GET /websites/oracle_en_industries_energy-water_digital-self-service_restapi

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-neighborcomparison-v1-bill-utilitycode-utilitycustomerid-fueltype-get

Retrieves a list of neighbor comparisons, ordered by start date. This endpoint allows users to compare their energy or water usage against neighbors and efficient neighbors within a specified period.

```APIDOC
## GET /websites/oracle_en_industries_energy-water_digital-self-service_restapi

### Description
Retrieves a list of neighbor comparisons, ordered by start date. This endpoint allows users to compare their energy or water usage against neighbors and efficient neighbors within a specified period.

### Method
GET

### Endpoint
/websites/oracle_en_industries_energy-water_digital-self-service_restapi

### Parameters
#### Query Parameters
- **start** (string) - Required - Inclusive start date of the period in ISO8601 format.
- **end** (string) - Required - Exclusive end date of the period in ISO8601 format.
- **fuelType** (string) - Optional - The type of fuel to compare (e.g., ELECTRICITY, GAS, COMBINED).

### Request Example
```json
{
  "start": "2023-01-01T00:00:00Z",
  "end": "2023-12-31T23:59:59Z",
  "fuelType": "ELECTRICITY"
}
```

### Response
#### Success Response (200)
- **description** (string) - Description of the neighbor comparison data.
- **type** (string) - The type of the returned data, expected to be 'array'.
- **items** (object) - Defines the schema for each item in the array. See `BillNeighborComparison` for details.
- **minItems** (integer) - Minimum number of items in the array.
- **maxItems** (integer) - Maximum number of items in the array.
- **uniqueItems** (boolean) - Indicates if all items in the array are unique.

#### Response Example
```json
{
    "description":"List of neighbor comparisons, ordered by start date.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/BillNeighborComparison"
    },
    "minItems":1,
    "maxItems":13,
    "uniqueItems":true
}
```

#### Error Response (400)
- **error** (object) - Contains error details.
  - **httpStatus** (integer) - The HTTP status code for the error.
  - **serviceErrorCode** (string) - An error code for the error (e.g., 'INVALID_DATE_RANGE', 'INVALID_DATE', 'INVALID_FUEL_TYPE').
  - **details** (string) - Details about the error (e.g., 'Start must be within the last 12 months', 'Start and end timestamp should be specified in ISO8601 format', 'Fuel type must be one of ELECTRICITY, GAS, COMBINED').

#### Error Response Example
```json
{
    "error":{
        "httpStatus":400,
        "serviceErrorCode":"INVALID_DATE_RANGE",
        "details":"Start must be within the last 12 months"
    }
}
```

### Nested Schema : BillNeighborComparison

#### Description
Represents a comparison of energy usage between a customer and their neighbors.

#### Fields
- **start** (string[date-time]) - Required - Inclusive start date of the period in ISO8601 format.
- **end** (string[date-time]) - Required - Exclusive end date of the period in ISO8601 format.
- **customerUsage** (number) - Required - Fuel usage value, in the specified units, for the customer.
- **allNeighborsUsage** (number) - Required - Mean fuel usage value, in the specified units, for the customer's neighbors.
- **efficientNeighborsUsage** (number) - Required - Mean fuel usage value, in the specified units, for the customer's efficient neighbors.

### Nested Schema : ErrorResponse

#### Description
Provides detailed information about an API error.

#### Fields
- **httpStatus** (integer) - Required - The HTTP status code for the error.
- **serviceErrorCode** (string) - Required - An error code for the error.
- **errorMessage** (string) - Short failure explanation.
- **details** (string) - Details about the error.
```

--------------------------------

### Example UsageResponse JSON for Energy Data

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-usage-v1-usage-raw-utilitycode-utilitycustomerid-fueltype-get

Provides a concrete example of the UsageResponse object, illustrating the expected format for utility code, customer ID, fuel type (ELECTRICITY), date range, unit (KWH), and detailed usage streams with intervals.

```json
{
    "response": {
        "utilityCode": "util",
        "utilityCustomerId": "9999990000-9999990000",
        "fuelType": "ELECTRICITY",
        "start": "2017-09-01T00:00:00-06:00",
        "end": "2017-09-01T00:30:00-06:00",
        "unit": "KWH",
        "streams": [
            {
                "utilityServicePointId": "12345001",
                "intervals": [
                    {
                        "start": "2017-09-01T00:00:00-06:00",
                        "end": "2017-09-01T00:15:00-06:00",
                        "usage": 0.14,
                        "readType": "ACTUAL"
                    },
                    {
                        "start": "2017-09-01T00:15:00-06:00",
                        "end": "2017-09-01T00:30:00-06:00",
                        "usage": 0.19,
                        "readType": "ACTUAL"
                    }
                ]
            }
        ]
    }
}
```

--------------------------------

### Example JSON Object for a Module

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-spark-v1-v2-modules-channel-names-get

This is an example of a JSON object representing a single module, conforming to the 'ModuleInfo' schema. It demonstrates the expected format for module ID, name, and description.

```json
{
    "id":"accf7256-66c8-11e9-a923-1681be663d3e",
    "name":"Tips Images V2",
    "moduleDescription":""
}
```

--------------------------------

### GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/list

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieves a list of relevant tips, sorted by expected energy savings.

```APIDOC
## GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/list

### Description
Retrieves a list of relevant tips. Sort order is the customer's expected energy savings for each tip, from highest to lowest savings.

### Method
GET

### Endpoint
/apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/list

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the customer.
- **utilityCode** (string) - Required - A 3- or 4-character representation of the client code, in all uppercase characters. Valid example "UTIL".

#### Query Parameters
- **locale** (string) - Optional - The locale to retrieve tips in language_territory format which uses two letters for language and territory. For example en_US or fr_FR. The customer locale is used as the default. Only locales supported by the utility are allowed.
- **limit** (string) - Optional - If limit not specified then all tips are retrieved.

### Request Example
```json
{
  "example": "Request body not applicable for this GET request."
}
```

### Response
#### Success Response (200)
- **TipListResponse** (object) - Contains a list of tips.

#### Response Example
```json
{
  "example": "{\"tips\": [{\"tipId\": \"tip1\", \"title\": \"Tip 1 Title\", \"description\": \"Description for tip 1.\", \"savings\": 15.0}, {\"tipId\": \"tip2\", \"title\": \"Tip 2 Title\", \"description\": \"Description for tip 2.\", \"savings\": 12.0}]}"
}
```

#### Error Responses
- **400** - Invalid request
- **401** - Authorization failure
- **404** - Customer not found or no tips found for the specified locale
- **500** - Internal error
```

--------------------------------

### Example Notification Preference Object (JSON)

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-notification-contact-v1-utilitycode-customers-id-notification_contacts-contactid-notification_preferences-get

An example of a notification preference object, specifying the communication channel and the type of event for which the preference is set.

```json
{
    "notificationChannel": "EMAIL",
    "eventType": "HOME_ENERGY"
}
```

```json
{
    "id": 1,
    "notificationChannel": "EMAIL",
    "eventType": "HOME_ENERGY"
}
```

--------------------------------

### GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/{tipId}

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieve a single tip with associated metadata for a customer.

```APIDOC
## GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/{tipId}

### Description
Retrieve a single tip with associated metadata for a customer.

### Method
GET

### Endpoint
/apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/{tipId}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the customer.
- **tipId** (integer) - Required - The unique identifier of the tip.
- **utilityCode** (string) - Required - A 3- or 4-character representation of the client code, in all uppercase characters. Valid example "UTIL".

#### Query Parameters
- **locale** (string) - Optional - The locale to retrieve the tip in language_territory format. For example en_US or fr_FR. The customer locale is used as the default. Only locales supported by the utility are allowed.

### Response
#### Success Response (200)
- **Tip** (object) - Successful operation. Schema defined in#/definitions/Tip.

#### Error Response (400, 401, 404, 500)
- **ErrorResponse** (object) - Details about the error. Schema defined in#/definitions/ErrorResponse.

#### Response Example
{
  "example": "{\"id\": 123, \"name\": \"Example Tip\", \"description\": \"This is an example tip.\", \"savings\": 75}"
}
```

--------------------------------

### 404 Not Found Error Response Example (JSON)

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-notification-contact-v1-utilitycode-customers-id-notification_contacts-get

An example of a 404 Not Found response. This signifies that the requested resource could not be found on the server. The `ErrorResponse` details which resource was not found, aiding in debugging.

```json
{
  "httpStatus": 404,
  "serviceErrorCode": "RESOURCE_NOT_FOUND",
  "errorMessage": "The requested resource was not found.",
  "details": "The specified endpoint or identifier does not exist."
}
```

--------------------------------

### GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieves a list of tips for a specific customer. Tips can be filtered by locale and channel.

```APIDOC
## GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips

### Description
Retrieves a list of tips for a specific customer. Tips can be filtered by locale and channel.

### Method
GET

### Endpoint
/apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips

### Parameters
#### Path Parameters
- **utilityCode** (string) - Required - A 3- or 4-character representation of the client code, in all uppercase characters. Valid example "UTIL".
- **id** (integer) - Required - The unique identifier of the customer.

#### Query Parameters
- **locale** (string) - Optional - The locale for which to retrieve tips (e.g., EN, FR). 
- **channel** (string) - Optional - Channel to retrieve tips (VOICE, WEB).

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **TipListResponse** (object) - A list of tips.

#### Response Example
```json
{
  "example": "response body"
}
```

#### Error Responses
- **400**: Invalid request
- **401**: Authorization failure
- **404**: Customer not found or no tips found for the specified locale
- **500**: Internal error
```

--------------------------------

### 404 Not Found Error Response Example

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-neighborcomparison-v1-bill-utilitycode-utilitycustomerid-fueltype-get

An example of a 404 Not Found error response as returned by the Oracle Energy and Water Digital Self-Service REST API. This example illustrates the expected format and content for common 'not found' scenarios.

```json
{
    "error": {
        "httpStatus": 404,
        "serviceErrorCode": "'ACCOUNT_NOT_FOUND' or 'SITE_NOT_FOUND' or 'CUSTOMER_NOT_FOUND'",
        "details": "'The customer does not have an active account for that given fuel type' or 'The customer does not have a service point for the given fuel type' or 'No customer with the given utilityCustomerId'"
    }
}
```

--------------------------------

### GET /websites/oracle_en_industries_energy-water_digital-self-service_restapi/{utilityCode}/{utilityCustomerId}/{fuelType}

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieves a neighbor comparison for a customer for each billing period within the specified time span. Data is available for the past 12 months, for a maximum of 13 bills. Any billing period partially or fully within the requested time span is included in the response. If start and end dates are not provided, the most recent neighbor comparison for the customer is returned.

```APIDOC
## GET /websites/oracle_en_industries_energy-water_digital-self-service_restapi/{utilityCode}/{utilityCustomerId}/{fuelType}

### Description
Returns a neighbor comparison for a customer for each billing period in the given time span. Data is available for the past 12 months, for a maximum of 13 bills. Any billing period partially or fully within the requested time span is included in the response. If start and end dates are not provided the most recent neighbor comparison for the customer is returned.

### Method
GET

### Endpoint
`/websites/oracle_en_industries_energy-water_digital-self-service_restapi/{utilityCode}/{utilityCustomerId}/{fuelType}`

### Parameters
#### Path Parameters
- **utilityCode** (string) - Required - A 3- or 4-character representation of the client code, in all caps. Valid example - UTIL.
- **utilityCustomerId** (string) - Required - The utility customer ID provided in the standard billing data integration.
- **fuelType** (string) - Required - The customer's fuel type. Must be one of: ELECTRICITY, GAS, COMBINED.

#### Query Parameters
- **start** (string) - Optional - The inclusive start date and time bounds in ISO8601 format. The default value is the start of the most recent complete billing period. The start value must be earlier than the end value.
- **end** (string) - Optional - The exclusive end date and time bounds in ISO8601 format. The default value is the end of the most recent complete billing period. The end value must be later than the start value.

#### Header Parameters
- **Authorization** (string) - Required - Oauth2 Bearer type id. For example, 'Bearer 00000000-0000-0000-0000-000000000000'

### Response
#### Success Response (200)
- **response** (object) - Contains the neighbor comparison data.
  - **utilityCode** (string) - The utility code.
  - **utilityCustomerId** (integer) - The utility customer ID.
  - **fuelType** (string) - The fuel type.
  - **start** (string) - The start date of the comparison period.
  - **end** (string) - The end date of the comparison period.
  - **unit** (string) - The unit of measurement for usage (e.g., KWH).
  - **neighborComparisons** (array) - An array of neighbor comparison objects.
    - **start** (string) - The start date of the billing period.
    - **end** (string) - The end date of the billing period.
    - **customerUsage** (number) - The customer's usage for the period.
    - **allNeighborsUsage** (number) - The average usage of all neighbors for the period.
    - **efficientNeighborsUsage** (number) - The average usage of efficient neighbors for the period.

#### Response Example
```json
{
  "response": {
    "utilityCode": "util",
    "utilityCustomerId": 12345,
    "fuelType": "ELECTRICITY",
    "start": "2013-09-01T00:00:00-06:00",
    "end": "2014-09-01T00:00:00-06:00",
    "unit": "KWH",
    "neighborComparisons": [
      {
        "start": "2013-08-20T00:00:00-06:00",
        "end": "2013-09-20T00:00:00-06:00",
        "customerUsage": 332,
        "allNeighborsUsage": 358.1,
        "efficientNeighborsUsage": 294.4
      },
      {
        "start": "2013-09-20T00:00:00-06:00",
        "end": "2013-10-20T00:00:00-06:00",
        "customerUsage": 375.1,
        "allNeighborsUsage": 382.7,
        "efficientNeighborsUsage": 298.2
      }
    ]
  }
}
```
```

--------------------------------

### Get Bill Neighbor Comparison (REST API)

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

This snippet demonstrates how to call the REST API to retrieve a customer's bill neighbor comparison. It requires utility code, customer ID, and fuel type as path parameters, and optionally accepts start and end dates for the desired time span. An authorization token is mandatory.

```curl
curl -X GET \
  'https://<api-url>/utilities/restapi/api/v1/customers/{utilityCode}/{utilityCustomerId}/{fuelType}/billNeighborComparison?start=2013-09-01T00:00:00-06:00&end=2014-09-01T00:00:00-06:00' \
  -H 'Authorization: Bearer <oauth2-token>'
```

--------------------------------

### ClickEngagement Example Data

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-customer-engagement-v1-utilities-utilitycode-engagements-clicks-get

An example of a single engagement event within the ClickEngagementResponse. It details communication specifics like product, event type, campaign, and click link, along with customer and utility identifiers.

```json
{
    "id": "accf6a68-66c8-11e9-a923-1681be663d3e",
    "product": "HER",
    "communicationEventType": "HOME_ENERGY",
    "trackId": "accf6cf2-66c8-11e9-a923-1681be663d3e",
    "campaignId": "accf6f22-66c8-11e9-a923-1681be663d3e",
    "moduleId": "accf7256-66c8-11e9-a923-1681be663d3e",
    "moduleMetadata": {
        "tipId": 2
    },
    "emailAddress": "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d",
    "occurredOn": "2018-02-19T13:02:00Z",
    "utilityCustomerId": "1872099045-387109999",
    "utilityInternalId": 1872099045,
    "utilityInternalId2": "18720-99045",
    "customerMultitenantId": "util-1872099045-387109999",
    "communicationMultitenantId": "util-8-e89ade",
    "clicklink": "http://example.com/app/?moduleId=accf7256-66c8-11e9-a923-1681be663d3e&tip_id=alpha"
}
```

--------------------------------

### SendEngagement Object Example (JSON)

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-customer-engagement-v1-utilities-utilitycode-engagements-sends-get

An example of a single engagement event returned in the API response. It details information about the communication sent, including IDs, types, timestamps, and customer identifiers.

```json
{
    "id": "accf6a68-66c8-11e9-a923-1681be663d3e",
    "product": "HER",
    "communicationEventType": "HOME_ENERGY",
    "eventType": "SENT",
    "trackId": "accf6cf2-66c8-11e9-a923-1681be663d3e",
    "campaignId": "accf6f22-66c8-11e9-a923-1681be663d3e",
    "moduleId": "accf7256-66c8-11e9-a923-1681be663d3e",
    "emailAddress": "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d",
    "occurredOn": "2018-02-19T13:00:00Z",
    "utilityCustomerId": "1872099045-387109999",
    "utilityInternalId": 1872099045,
    "utilityInternalId2": "18720-99045",
    "customerMultitenantId": "util-1872099045-387109999",
    "communicationMultitenantId": "util-8-e89ade"
}
```

--------------------------------

### GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/{tipId}

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieves a single tip based on customer and tip identifiers.

```APIDOC
## GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/{tipId}

### Description
Retrieves a single tip based on customer and tip identifiers.

### Method
GET

### Endpoint
/apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips/{tipId}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the customer.
- **tipId** (string) - Required - The unique identifier of the tip.
- **utilityCode** (string) - Required - A 3- or 4-character representation of the client code, in all uppercase characters. Valid example "UTIL".

#### Query Parameters
- **locale** (string) - Optional - The locale to retrieve tips in language_territory format which uses two letters for language and territory. For example en_US or fr_FR. The customer locale is used as the default. Only locales supported by the utility are allowed.

### Request Example
```json
{
  "example": "Request body not applicable for this GET request."
}
```

### Response
#### Success Response (200)
- **SingleTipResponse** (object) - Contains details of a single tip.

#### Response Example
```json
{
  "example": "{\"tipId\": \"some-tip-id\", \"title\": \"Sample Tip Title\", \"description\": \"This is a sample tip description.\", \"savings\": 10.5}"
}
```

#### Error Responses
- **400** - Invalid request
- **401** - Authorization failure
- **404** - Customer not found or no tips found for the specified locale
- **500** - Internal error
```

--------------------------------

### ComplaintEngagement Example Object

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-customer-engagement-v1-utilities-utilitycode-engagements-complaints-get

An example of a single engagement event within the API response. It details specific customer interaction data, including product, event type, timestamps, and various customer identifiers.

```json
{
    "id": "accf6a68-66c8-11e9-a923-1681be663d3e",
    "product": "HER",
    "communicationEventType": "HOME_ENERGY",
    "eventType": "SPAM_COMPLAINT",
    "trackId": "accf6cf2-66c8-11e9-a923-1681be663d3e",
    "campaignId": "accf6f22-66c8-11e9-a923-1681be663d3e",
    "moduleId": "accf7256-66c8-11e9-a923-1681be663d3e",
    "emailAddress": "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d",
    "occurredOn": "2018-02-19T13:04:00Z",
    "utilityCustomerId": "1872099045-387109999",
    "utilityInternalId": 1872099045,
    "utilityInternalId2": "18720-99045",
    "customerMultitenantId": "util-1872099045-387109999",
    "communicationMultitenantId": "util-8-e89ade"
}
```

--------------------------------

### Example 404 Customer Account Not Found Response

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-disaggregation-v1-utilities-utilitycode-customers-customerid-bills-consumption-categories-get

An example JSON response for a 404 Not Found error, specifically when a customer account cannot be located. The error message includes the account ID and a unique identifier for the error instance.

```json
{
    "error": {
        "httpStatus": 404,
        "errorMessage": "Account 00000000 not found. (917aab1d-b12a-4df9-b85d-968cc017a96e) "
    }
}
```

--------------------------------

### GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieve a sorted list of tip names for a particular customer. The sorting is based on the customer's expected energy savings for each tip, from highest to lowest.

```APIDOC
## GET /apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips

### Description
Retrieve a sorted list of tip names for a particular customer. Sort order is the customer's expected energy savings for each tip, from highest to lowest savings.

### Method
GET

### Endpoint
/apis/tips-v1/{utilityCode}/energy_guide/customers/{id}/tips

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the customer.
- **utilityCode** (string) - Required - A 3- or 4-character representation of the client code, in all uppercase characters. Valid example "UTIL".

#### Query Parameters
- **locale** (string) - Optional - The locale to retrieve tips in language_territory format. For example en_US or fr_FR. The customer locale is used as the default. Only locales supported by the utility are allowed.
- **limit** (string) - Optional - If limit not specified then all tips are retrieved.
- **channel** (string) - Optional - Channel to retrieve tips (VOICE, WEB).

### Response
#### Success Response (200)
- **TipNamesListResponse** (object) - Successful operation. Schema defined in#/definitions/TipNamesListResponse.

#### Error Response (400, 401, 404, 500)
- **ErrorResponse** (object) - Details about the error. Schema defined in#/definitions/ErrorResponse.

#### Response Example
{
  "example": "{\"tips\": [{\"name\": \"Tip Name 1\", \"savings\": 100}, {\"name\": \"Tip Name 2\", \"savings\": 50}]}"
}
```

--------------------------------

### Example JSON Response: Bill Disaggregation

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-disaggregation-v1-utilities-utilitycode-customers-customerid-bills-consumption-categories-get

This is an example of a successful (200 OK) JSON response for a bill disaggregation request. It includes a breakdown of costs and usage across various categories for a specific billing period.

```json
{
    "response": {
        "categories": [
            {
                "name": "APPLIANCES",
                "ratio": 0.05,
                "cost": 490,
                "usage": 4900
            },
            {
                "name": "CLOTHES_WASHER",
                "ratio": 0.01,
                "cost": 110,
                "usage": 1100
            },
            {
                "name": "COOLING",
                "ratio": 0.26,
                "cost": 2600,
                "usage": 26000
            },
            {
                "name": "DRYER",
                "ratio": 0.01,
                "cost": 220,
                "usage": 2200
            },
            {
                "name": "ELECTRIC_VEHICLE",
                "ratio": 0.08,
                "cost": 760,
                "usage": 7600
            },
            {
                "name": "ELECTRONICS",
                "ratio": 0.09,
                "cost": 863,
                "usage": 8630
            },
            {
                "name": "HEATING",
                "ratio": 0.29,
                "cost": 2892,
                "usage": 28920
            },
            {
                "name": "LIGHTING",
                "ratio": 0.02,
                "cost": 235,
                "usage": 2350
            },
            {
                "name": "OTHER",
                "ratio": 0.04,
                "cost": 406,
                "usage": 4060
            },
            {
                "name": "POOL",
                "ratio": 0.08,
                "cost": 824,
                "usage": 8240
            },
            {
                "name": "REFRIGERATOR",
                "ratio": 0.01,
                "cost": 160,
                "usage": 1600
            },
            {
                "name": "GAS_APPLIANCES_OTHER",
                "ratio": 0.01,
                "cost": 160,
                "usage": 160
            }
        ]
    }
}
```

--------------------------------

### Example JSON Response for Annual Disaggregation

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/op-apis-disaggregation-v1-utilities-utilitycode-customers-customerid-consumption-categories-get

An example of a 200 OK response body for the annual disaggregation API endpoint. This JSON object illustrates the structure and typical data for usage categories and their ratios.

```json
{
    "response": {
        "categories": [
            {
                "name": "APPLIANCES",
                "ratio": 0.09
            },
            {
                "name": "COOLING",
                "ratio": 0.02
            },
            {
                "name": "ELECTRIC_VEHICLE",
                "ratio": 0.2
            },
            {
                "name": "ELECTRONICS",
                "ratio": 0.13
            },
            {
                "name": "HEATING",
                "ratio": 0.22
            },
            {
                "name": "LIGHTING",
                "ratio": 0.04
            },
            {
                "name": "OTHER",
                "ratio": 0.06
            },
            {
                "name": "POOL",
                "ratio": 0.13
            },
            {
                "name": "GAS_APPLIANCES_OTHER",
                "ratio": 0.02
            },
            {
                "name": "AIR_CONDITION",
                "ratio": 0.07
            },
            {
                "name": "TOTAL",
                "ratio": 1
            },
            {
                "name": "WATER_HEATING",
                "ratio": 0.11
            }
        ]
    }
}
```

--------------------------------

### GET /websites/oracle_en_industries_energy-water_digital-self-service_restapi/usage/day

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieves daily energy and water usage data for a specified customer and date range.

```APIDOC
## GET /websites/oracle_en_industries_energy-water_digital-self-service_restapi/usage/day

### Description
Retrieves daily energy and water usage data for a specified customer and date range. This endpoint is useful for analyzing consumption patterns over a 24-hour period.

### Method
GET

### Endpoint
/websites/oracle_en_industries_energy-water_digital-self-service_restapi/usage/day

### Parameters
#### Query Parameters
- **utilityCode** (string) - Required - The 3 or 4 character code for the utility company; for example util.
- **utilityCustomerId** (string) - Required - The utility customer identifier in the request.
- **fuelType** (string) - Required - The fuel type in the request, for example, GAS or ELECTRICITY.
- **start** (string) - Required - The start date in the request (ISO8601 format).
- **end** (string) - Required - The end date in the request (ISO8601 format).
- **unit** (string) - Optional - The unit of measurement for fuel usage values (e.g., KWH, THERMS).

### Request Example
```
GET /websites/oracle_en_industries_energy-water_digital-self-service_restapi/usage/day?utilityCode=util&utilityCustomerId=9999990000-9999990000&fuelType=ELECTRICITY&start=2017-09-01T00:00:00-06:00&end=2017-09-01T23:59:59-06:00
```

### Response
#### Success Response (200)
- **utilityCode** (string) - The utility company code.
- **utilityCustomerId** (string) - The utility customer identifier.
- **fuelType** (string) - The type of fuel (e.g., ELECTRICITY, GAS).
- **start** (string) - The start of the usage period (ISO8601 format).
- **end** (string) - The end of the usage period (ISO8601 format).
- **timezone** (string) - The timezone of the usage data.
- **unit** (string) - The unit of measurement for usage (e.g., KWH).
- **streams** (array) - An array of UsageStream objects, each containing usage intervals.

##### UsageStream Object
- **utilityServicePointId** (string) - Identifier for the service point.
- **intervals** (array) - An array of UsageInterval objects.

###### UsageInterval Object
- **start** (string) - The start of the interval (ISO8601 format).
- **end** (string) - The end of the interval (ISO8601 format).
- **usage** (number) - The energy usage during the interval.
- **readType** (string) - The type of reading (e.g., ACTUAL, ESTIMATED).

#### Response Example
```json
{
    "utilityCode": "util",
    "utilityCustomerId": "9999990000-9999990000",
    "fuelType": "ELECTRICITY",
    "start": "2017-09-01T00:00:00-06:00",
    "end": "2017-09-01T23:59:59-06:00",
    "timezone": "America/Denver",
    "unit": "KWH",
    "streams": [
        {
            "utilityServicePointId": "12345001",
            "intervals": [
                {
                    "start": "2017-09-01T00:00:00-06:00",
                    "end": "2017-09-01T00:15:00-06:00",
                    "usage": 0.14,
                    "readType": "ACTUAL"
                },
                {
                    "start": "2017-09-01T00:15:00-06:00",
                    "end": "2017-09-01T00:30:00-06:00",
                    "usage": 0.19,
                    "readType": "ACTUAL"
                }
            ]
        }
    ]
}
```
```

--------------------------------

### GET /apis/programDesign-v1/v1/utilities/{utilityCode}/tracks/names

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Fetches the names and IDs of tracks and campaigns associated with a specific utility.

```APIDOC
## GET /apis/programDesign-v1/v1/utilities/{utilityCode}/tracks/names

### Description
Returns a list of tracks and campaigns with their corresponding ids and names.

### Method
GET

### Endpoint
/apis/programDesign-v1/v1/utilities/{utilityCode}/tracks/names

### Parameters
#### Path Parameters
- **utilityCode** (string) - Required - The utility code for which to retrieve track and campaign names.

### Request Example
```json
{
  "example": "(No request body for GET request)"
}
```

### Response
#### Success Response (200)
- **array of PublicTrackInfo** (array) - A list of objects, where each object contains the id and name of a track or campaign.

#### Response Example
```json
{
  "example": "(Example of PublicTrackInfo schema)"
}
```
```

--------------------------------

### GET /apis/spark-v1/v2/modules/{channel}/names

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieves a list of module names based on the specified channel.

```APIDOC
## GET /apis/spark-v1/v2/modules/{channel}/names

### Description
Returns a list of modules by channel which represents the module id to name and description binding for any version of modules. If no modules were found, the server will return an empty list.

### Method
GET

### Endpoint
/apis/spark-v1/v2/modules/{channel}/names

### Parameters
#### Path Parameters
- **channel** (string) - Required - The channel for which to retrieve module names.

### Request Example
```json
{
  "example": "(No request body for GET request)"
}
```

### Response
#### Success Response (200)
- **array of ModuleIdToName** (array) - A list of objects, where each object binds a module ID to its name and description.

#### Response Example
```json
{
  "example": "(Example of ModuleIdToName schema)"
}
```
```

--------------------------------

### GET /apis/bill-comparison-v2/{utilityCode}/bill-comparison/accounts/{utilityAccountId}

Source: https://docs.oracle.com/en/industries/energy-water/digital-self-service/restapi/swagger

Retrieves bill comparison data for a specific utility account. It allows for fallback options and specifying a reference date.

```APIDOC
## GET /apis/bill-comparison-v2/{utilityCode}/bill-comparison/accounts/{utilityAccountId}

### Description
Retrieves bill comparison data for a specific utility account. This endpoint allows for specifying fallback behavior and a reference date for billing periods.

### Method
GET

### Endpoint
`/apis/bill-comparison-v2/{utilityCode}/bill-comparison/accounts/{utilityAccountId}`

### Parameters
#### Path Parameters
- **utilityCode** (string) - Required - The unique code for the utility provider.
- **utilityAccountId** (string) - Required - The unique identifier for the utility account.

#### Query Parameters
- **fallbackToPreviousPeriod** (boolean) - Optional - Defaults to true. Whether to use fallback from YEAR_AGO to PREVIOUS on missed bills.
- **asOf** (date) - Optional - Defaults to NOW. The most recent bill that ends before the asOf date is chosen as the reference one.

### Request Example
```json
{
  "fallbackToPreviousPeriod": true,
  "asOf": "2023-10-27"
}
```

### Response
#### Success Response (200)
- **billComparisonResponse** (object) - Contains the bill comparison data. (Schema details not provided in input)

#### Error Response
- **notAuthorizedErrorResponse** (object) - Returned on authorization failure. (Schema details not provided in input)
- **notFoundErrorResponse** (object) - Returned when the utility account is not found. (Schema details not provided in input)
- **internalServerErrorResponse** (object) - Returned on internal server error. (Schema details not provided in input)

#### Response Example (Success)
(Schema details not provided in input for billComparisonResponse)

#### Response Example (Error)
(Schema details not provided in input for error responses)
```
Tokens:
Raw