# Payloads
## Limit Request Event Payload
Example of the request payload for limit request event sent by the VTN.
```json
{
// Unique ID of the event
"id": "1",
// Human readable name that can be used for debugging
"eventName": "powerLimit",
"objectType": "EVENT",
"programID": "1",
// The duration of the event
"intervalPeriod": {
"start": "2023-10-20T12:00:00Z",
"duration": "PT15M" // 15 minutes specified in ISO 8601
},
"reportDescriptors": [
// If an acknowledgement report is requested here it should be sent
// as soon as the event is received.
{
"payloadType": "POWER_LIMIT_ACKNOWLEDGEMENT",
"startInterval": 0,
"historical": false
}
],
"payloadDescriptors": [
{
// For a production resource this will be "PRODUCTION_POWER_LIMIT" instead
"payloadType": "CONSUMPTION_POWER_LIMIT",
// Specifies the unit of the power limit (always KW).
"units": "KW"
},
{
"payloadType": "POWER_LIMIT_VERSION"
},
// The three payloads below will not be present until validation has occurred!
{
"payloadType": "POWER_LIMIT_VALIDATION_STATUS"
},
{
"payloadType": "POWER_LIMIT_VALIDATION_TIMESTAMP"
},
{
"payloadType": "POWER_LIMIT_VALIDATION_READING",
// Specifies the unit of the power limit (always KW).
"units": "KW"
}
],
"intervals": [{
// Sequential ID for the interval. Will always be 0 since there will only be one interval.
"id": 0,
"payloads": [
{
// For a production asset this will be "PRODUCTION_POWER_LIMIT" instead
"type": "CONSUMPTION_POWER_LIMIT",
// The actual power limit - 15 000 KW
"values": [15000]
},
{
"type": "POWER_LIMIT_VERSION",
// The version of the limit.
// In case the limit (CONSUMPTION_POWER_LIMIT or PRODUCTION_POWER_LIMIT) is updated
// after the creation of the event, this value will be incremented. Note that only
// if the resource is configured to support dynamic limits can the limit change,
// otherwise both the limit and this value will be static after the event has been created.
"values": [1]
}
// The three payloads below will not be present until validation has occurred!
{
"type": "POWER_LIMIT_VALIDATION_STATUS",
// Status of the validation. Possible values:
// - ok: validation succeeded (resource was below limit)
// - not_ok: validation failed (resource was above limit)
// - unable_to_validate: validation could not run, e.g due to missing readings or a bad configuration
"values": ["ok"]
},
{
"type": "POWER_LIMIT_VALIDATION_STATUS_TEXT",
// Human readable explanation of the status for debugging purposes.
"values": ["Validation succeeded."]
},
{
"type": "POWER_LIMIT_VALIDATION_TIMESTAMP",
// The time & date when the validation was run.
"values": ["2023-10-20T12:25:00Z"]
},
{
"type": "POWER_LIMIT_VALIDATION_READING",
// The reading value that was used for validation. Might be an average of several readings.
"values": [14000]
}
]
}],
"targets": [
{
"type": "RESOURCE_NAME",
// Corresponds to the SWITCH resource ID.
// This is the resource for which the power limit should be applied to.
"values": ["1"]
},
{
"type": "ORGANIZATION_ID",
// Corresponds to the SWITCH organization ID.
// For the FSP this is your own organization ID.
"values": ["1"]
}
]
}
```
## Acknowledgement Report Payload
Example of the acknowledgement report request payload sent by VEN.
{% hint style="info" %}
The first time a particular event is received, or if a previously received event is received again but with an incremented `POWER_LIMIT_VERSION`, the client should immediately respond with the report below to indicate that they have received the event.
{% endhint %}
{% hint style="warning" %}
You should not send multiple acknowledgements to the same event unless the `POWER_LIMIT_VERSION` has increased.
{% endhint %}
{% hint style="warning" %}
Do not send acknowledgements to events which do not contain the `POWER_LIMIT_ACKNOWLEDGEMENT` report descriptor. Such events target resources which have been configured to not use acknowledgements.
{% endhint %}
```json
{
// The ID of the event which was just received
"eventID": "1",
// Should be the same as the events program ID
"programID": "1",
// SWITCH is not using this field for anything, but it's required by the specification.
// Can be set to a descriptive name for your integration (for debugging purposes).
"clientName": "",
"payloadDescriptors": [{
"payloadType": "POWER_LIMIT_ACKNOWLEDGEMENT"
}],
"resources": [{
// The resource for which the power limit has been applied to (see RESOURCE_NAME in the event payload).
"resourceName": "1",
// Needs to be the same as the interval period for the event.
"intervalPeriod": {
"start": "2023-10-20T12:00:00Z",
"duration": "PT15M"
},
"intervals": [{
// Sequential ID for the interval. Should always be 0 since there will only be one interval.
"id": 0,
"payloads": [{
"type": "POWER_LIMIT_ACKNOWLEDGEMENT",
// The version of the power limit which the acknowledgement is intended for.
// Only the latest version can be acknowledged.
// See POWER_LIMIT_VERSION in the event payload.
"values": [1]
}]
}]
}]
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.switchmarket.se/openadr-3/payloads.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.