Download OpenAPI specification:Download
The API enables users to provide grid services from their asset portfolio. Use these endpoints to monitor meter inventory, place bids and receive dispatches.
Login with email / password and receive a token which is required in subsequent requests.
email required | string The emailaddress associated to the account. |
password required | string The password for the account. |
{- "email": "{{email}}",
- "password": "{{password}}"
}
{- "token": "string",
- "refresh_token": "string"
}
Search meters on your account. Returns all meters by default.
accountId required | string |
date_added_from | string <date-time> Returns only meters that have been added from this date (inclusive) |
date_added_to | string <date-time> Returns only meters that have been added to this date (inclusive) |
page_token | string Token of the page to request.
|
page_size | integer Default: 500 The number of meters to retrieve per page. |
{- "date_added_from": "2021-01-12T21:12:46.784Z",
- "date_added_to": "2021-05-25T21:12:46.784Z"
}
{- "next_page_token": "string",
- "results": [
- {
- "meter_id": "f5bfd5fa-87fd-444b-98ad-bef6cdbd5c59",
- "partner_reference": "meter1",
- "transmission_region": "CAISO",
- "utility": "SCE",
- "load_serving_entity": "lse",
- "participation": [
- {
- "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
- "trade_date": "2021-06-02T07:00:00Z"
}, - {
- "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
- "trade_date": "2021-06-03T07:00:00Z"
}, - {
- "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
- "trade_date": "2021-06-04T07:00:00Z"
}
], - "load_zone": "lap",
- "service_point_number": "SAN-4693158213",
- "customer_name": "Aaron Murphy",
- "service_address_full": "658nd Street, 65247 Eyver, California, US",
- "service_address": {
- "street_1": "658nd Street",
- "street_2": null,
- "postal_code": "65247",
- "city": "Eyver",
- "state_or_province": "California",
- "country": "US"
}, - "enrollment": {
- "status": "Eligible",
- "active_from": null,
- "active_to": null,
- "eligible_from": "2021-05-19T07:00:00Z",
- "eligible_to": "2029-01-02T08:00:00Z",
- "status_reasons": [ ],
- "partner_preferred_action": "Idle",
- "partner_indicated_idle_period": {
- "from": "2021-10-10T07:00:00Z",
- "to": "2022-05-10T07:00:00Z",
- "reasons": [ ]
}, - "partner_indicated_disenrollment": null
}, - "created_at": "2021-05-19T12:54:17.224155Z",
- "tariff": "TOUD-4-9PM-SDP-O"
}
]
}
accountId required | string |
meterId required | string |
{- "meter_id": "afce893d-ea68-487f-9f8c-778b1881f60a",
- "partner_reference": "meter1",
- "transmission_region": "CAISO",
- "utility": "SCE",
- "load_serving_entity": "lse",
- "participation": [
- {
- "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
- "trade_date": "2021-06-02T07:00:00Z"
}, - {
- "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
- "trade_date": "2021-06-03T07:00:00Z"
}, - {
- "market_group_id": "959b2bfb-ec22-4fdf-be54-173639c4e925",
- "trade_date": "2021-06-04T07:00:00Z"
}
], - "load_zone": "lap",
- "service_point_number": "SAN-0250508399",
- "customer_name": "Andrea Morris",
- "service_address_full": "914nd Street, 42908 Seah, California, US",
- "service_address": {
- "street_1": "914nd Street",
- "street_2": null,
- "postal_code": "42908",
- "city": "Seah",
- "state_or_province": "California",
- "country": "US"
}, - "enrollment": {
- "status": "Active",
- "active_from": "2021-05-19T07:00:00Z",
- "active_to": "2021-12-31T08:00:00Z",
- "eligible_from": "2021-05-19T07:00:00Z",
- "eligible_to": "2029-01-02T08:00:00Z",
- "status_reasons": [ ],
- "partner_preferred_action": "Enroll",
- "partner_indicated_idle_period": {
- "from": "2022-05-10T07:00:00Z",
- "to": "2022-05-30T07:00:00Z",
- "reasons": [ ]
}, - "partner_indicated_disenrollment": {
- "from": "2022-07-01T07:00:00Z",
- "reasons": [
- {
- "code": "PART_0001",
- "comment": "The Meter is not assigned to participate in the energy market"
}
]
}
}, - "created_at": "2021-05-19T12:54:09.99249Z",
- "tariff": "HETOUC"
}
Returns information about the standing bids that have been placed.
accountId required | string |
next_page_token | string Token of the page to request. Null to request a new batch of results. |
start_date required | string <date-time> Start datetime range to get standing bids for (inclusive). |
end_date required | string <date-time> End datetime range to get standing bids for (inclusive). |
meter_ids | Array of strings <uuid> Meter ids to get bids for. Limited at 100 meters per request |
{- "next_page_token": "",
- "start_date": "2021-05-18T08:00:00Z",
- "end_date": "2021-12-31T08:00:00Z",
- "meter_ids": [
- "{{meterId}}"
]
}
{- "next_page_token": "NzBjNzU1ZWQtMzM5NC00YmIwLTkwZDAtZDMzN2IyZmZiNTNi",
- "results": [
- {
- "meter_id": "0b8894b3-5b27-48ff-a23f-bced0d137ffa",
- "start_time": "2021-06-01T07:00:00Z",
- "end_time": "2021-06-30T07:00:00Z",
- "day_type": "business",
- "hours": [
- {
- "hour_ending": 19,
- "curve": [
- {
- "quantity_in_kw": 15,
- "price": 0.1
}
]
}, - {
- "hour_ending": 20,
- "curve": [
- {
- "quantity_in_kw": 15,
- "price": 0.1
}
]
}
]
}, - {
- "meter_id": "0b8894b3-5b27-48ff-a23f-bced0d137ffa",
- "start_time": "2021-07-01T07:00:00Z",
- "end_time": "2021-07-31T07:00:00Z",
- "day_type": "business",
- "hours": [
- {
- "hour_ending": 19,
- "curve": [
- {
- "quantity_in_kw": 18,
- "price": 0.15
}
]
}, - {
- "hour_ending": 20,
- "curve": [
- {
- "quantity_in_kw": 18,
- "price": 0.15
}
]
}
]
}
]
}
Use standing bids to schedule consistent bidding activity over a period of time (e.g. month, year, week).
By placing a standing bid, the system repeats bids on a defined schedule. Standing bids will be submitted to the market one day before the trading day. After processing, bids that are placed here will be visible in the Search Bids endpoint.
Datetimes reflect a start and end to the bidding interval in Coordinated Universal Time (UTC).
hour_ending
denotes the time at the end of a bidding hour ("hour_ending": 16
denotes a bid from 15:00 to 16:00)
Cancel or overwrite an existing standing bid by submitting a new curve for the same meter in an overlapping time period.
accountId required | string |
required | Array of objects (StandingBid) [ items ] |
{- "standing_bids": [
- {
- "meter_id": "{{meterId}}",
- "start_time": "2021-05-30T18:00:00Z",
- "end_time": "2021-07-01T18:00:00Z",
- "day_type": "business",
- "hours": [
- {
- "hour_ending": 17,
- "curve": [
- {
- "quantity_in_kw": 5,
- "price": 0.7
}, - {
- "quantity_in_kw": 50,
- "price": 0.95
}
]
}, - {
- "hour_ending": 18,
- "curve": [
- {
- "quantity_in_kw": 9,
- "price": 0.9
}, - {
- "quantity_in_kw": 75,
- "price": 0.95
}
]
}
]
}
]
}
{- "validations": [ ],
- "stored": [
- {
- "meter_id": "f5bfd5fa-87fd-444b-98ad-bef6cdbd5c59",
- "start_time": "2021-09-01T07:00:00Z",
- "end_time": "2021-10-01T07:00:00Z",
- "day_type": "business",
- "hours": [
- {
- "hour_ending": 17,
- "curve": [
- {
- "quantity_in_kw": 5,
- "price": 0.7
}, - {
- "quantity_in_kw": 50,
- "price": 0.95
}
]
}, - {
- "hour_ending": 18,
- "curve": [
- {
- "quantity_in_kw": 9,
- "price": 0.9
}, - {
- "quantity_in_kw": 75,
- "price": 0.95
}
]
}
]
}
], - "deleted": [ ]
}
Bids are sets of pairs (Price, Capacity) from which a bid curve is constructed. The bid curve is the function of the form Price = F(Capacity) which determines at which price a demand response provider is willing to curtail a certain volume of load.
Initial bids must be placed at least 24 hours before the start of the trading day.
Example: A storage provider is bidding in capacity. A sample bid for a given hour may have the form shown in the table below:
Price ($/kWh) | 0.18 | 0.24 | 0.28 | 0.34 | 0.45 |
---|---|---|---|---|---|
Capacity | 40 | 80 | 200 | 400 | 600 |
According to this bid, the provider is willing to curtail the first 40kW of load for 18 cents per kWh. If a greater volume is needed, the same provider is willing to curtail any amount of energy from zero up to 80 kW at $0.24/kWh, up to 200 kW for $0.28/kWh, up to 400 kW for $0.34/kWh and up to 600 kW for $0.45/kWh.
Bid quantities have a minimum granularity of 1kW. Bids of 1.5kW for instance will be rejected. Only values that are a multiple of 1 will be accepted.
All datetimes must be provided in the UTC timezone
Bids can be modified by placing a new bid for the same meter/timeslot combination. The previous curve will be completely replaced by the new curve.
A bid can be cancelled until the market closes. Cancel a bid by submitting an empty curve for a meter/timeslot combination.
Successful responses will return a copy of the JSON objects provided in the request. Each point in the curve will contain an additional status field indicating if the bid has been received, accepted or rejected.
Received - Bid has been received by DEX, but still has to be validated Accepted - Bid has been accepted for processing by the market Rejected - Bid has not been accepted by the market Error - An unforeseen case occurred, theoretically bids will never enter this state
Open - Market is open and accepting new bids, Accepted and Rejected bids can still be updated Processing - Market is closed and processing bids Closed - Market is closed and finished processing, potential dispatches are available through the get dispatches API call (1.5 Get dispatches)
Note: on a successful bid a HTTP 202 response is explicitly returned to indicate that the bid still has to be processed by our market. The response only indicates that the bid is placed in the queue to be processed as soon as possible. This can take several minutes until the bid with actual status will be visible in the get bids API call.
accountId required | string |
currency required | string |
required | Array of objects (Bid) [ items ] |
{- "currency": "USD",
- "bids": [
- {
- "meter_id": "f5bfd5fa-87fd-444b-98ad-bef6cdbd5c59",
- "timeslots": [
- {
- "start_time": "2021-07-19T01:00:00Z",
- "end_time": "2021-07-19T02:00:00Z",
- "curve": [
- {
- "quantity_in_kw": 100,
- "price": 1
}
]
}, - {
- "start_time": "2021-07-19T02:00:00Z",
- "end_time": "2021-07-19T03:00:00Z",
- "curve": [
- {
- "quantity_in_kw": 100,
- "price": 1
}
]
}
]
}
]
}
{- "validations": [ ],
- "currency": "USD",
- "results": [
- {
- "meter_id": "afce893d-ea68-487f-9f8c-778b1881f60a",
- "timeslots": [
- {
- "start_time": "2021-06-07T02:00:00Z",
- "end_time": "2021-06-07T03:00:00Z",
- "curve": [
- {
- "quantity_in_kw": 100,
- "price": 1
}
], - "version": 1,
- "bid_status": "Accepted",
- "market_status": "Open"
}, - {
- "start_time": "2021-06-07T01:00:00Z",
- "end_time": "2021-06-07T02:00:00Z",
- "curve": [
- {
- "quantity_in_kw": 100,
- "price": 1
}
], - "version": 1,
- "bid_status": "Accepted",
- "market_status": "Open"
}
]
}
]
}
Search between start_date and end_date for a list of meters identified by meter_id in meter_ids.
A start and end date must be specified when requesting bids. The maximum timespan for a single request is 24 hours.
accountId required | string |
start_date required | string |
end_date required | string |
meter_ids required | Array of strings |