Create a VPP enrollment

curl --request POST \
  --url https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "program_id": "vpr_6a1f8e375db9de605baadd46"
}
'

import requests

url = "https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments"

payload = { "program_id": "vpr_6a1f8e375db9de605baadd46" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({program_id: 'vpr_6a1f8e375db9de605baadd46'})
};

fetch('https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'program_id' => 'vpr_6a1f8e375db9de605baadd46'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments"

	payload := strings.NewReader("{\n  \"program_id\": \"vpr_6a1f8e375db9de605baadd46\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"program_id\": \"vpr_6a1f8e375db9de605baadd46\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"program_id\": \"vpr_6a1f8e375db9de605baadd46\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "enr_7c2f1a9e4b0d8f3a6e2c5d10",
  "object": "vpp_enrollment",
  "live_mode": true,
  "operator": {
    "id": "opr_8587fa49c7e5297ccc6c57e5",
    "display_name": "Pick",
    "logo_url": "https://s.flatpeak.com/83b06a60e38c2.png",
    "support_email": "help@pick.com"
  },
  "program": {
    "id": "vpr_6a1f8e375db9de605baadd46",
    "display_name": "Community Powershare",
    "url": "https://pick.com/programs/community-powershare",
    "dispatch_test_required": true,
    "managed": false
  },
  "device_id": "dev_63a6087272941ef077a8fd3e",
  "location_id": "loc_641b90b758fb8e6293716e40",
  "state_data_delayed": false,
  "device_meters_data_delayed": false,
  "enrollment_state": "ACTIVE",
  "enrollment_step": "ACTIVE",
  "enrollment_state_timeline": [
    {
      "state": "ACTIVE",
      "step": "ACTIVE",
      "step_status": "COMPLETE",
      "description": "Your device is dispatching.",
      "time_occurred": "2026-03-05T00:00:00Z",
      "time_expected": "2026-03-04T09:00:00Z",
      "time_created": "2026-11-07T05:30:02Z",
      "suspension_reasons": [
        "DISPATCH_UNRESPONSIVE"
      ],
      "metadata": "Device properties changed, registration update successful. Reference XM2345TYUQ."
    }
  ],
  "time_updated": "2023-11-07T05:31:56Z",
  "time_created": "2023-11-07T05:31:56Z",
  "account_id": "acc_661677911f2197045e6cf1b1",
  "suspension_reasons": [
    "TELEMETRY_STALLED"
  ],
  "warnings": [
    "TELEMETRY_STALLED"
  ],
  "terms": {
    "rewards": [
      {
        "basis": "FIXED",
        "rate": 15,
        "period": "QUARTER"
      },
      {
        "basis": "DELIVERED_KWH",
        "rate": 0.35
      }
    ],
    "opt_out_policy": "ALLOWED",
    "notice_days": 30
  }
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

POST

devices

{device_id}

vpp-enrollments

Create a VPP enrollment

curl --request POST \
  --url https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "program_id": "vpr_6a1f8e375db9de605baadd46"
}
'

import requests

url = "https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments"

payload = { "program_id": "vpr_6a1f8e375db9de605baadd46" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({program_id: 'vpr_6a1f8e375db9de605baadd46'})
};

fetch('https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'program_id' => 'vpr_6a1f8e375db9de605baadd46'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments"

	payload := strings.NewReader("{\n  \"program_id\": \"vpr_6a1f8e375db9de605baadd46\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"program_id\": \"vpr_6a1f8e375db9de605baadd46\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://energy-api.flatpeak.com/devices/{device_id}/vpp-enrollments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"program_id\": \"vpr_6a1f8e375db9de605baadd46\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "enr_7c2f1a9e4b0d8f3a6e2c5d10",
  "object": "vpp_enrollment",
  "live_mode": true,
  "operator": {
    "id": "opr_8587fa49c7e5297ccc6c57e5",
    "display_name": "Pick",
    "logo_url": "https://s.flatpeak.com/83b06a60e38c2.png",
    "support_email": "help@pick.com"
  },
  "program": {
    "id": "vpr_6a1f8e375db9de605baadd46",
    "display_name": "Community Powershare",
    "url": "https://pick.com/programs/community-powershare",
    "dispatch_test_required": true,
    "managed": false
  },
  "device_id": "dev_63a6087272941ef077a8fd3e",
  "location_id": "loc_641b90b758fb8e6293716e40",
  "state_data_delayed": false,
  "device_meters_data_delayed": false,
  "enrollment_state": "ACTIVE",
  "enrollment_step": "ACTIVE",
  "enrollment_state_timeline": [
    {
      "state": "ACTIVE",
      "step": "ACTIVE",
      "step_status": "COMPLETE",
      "description": "Your device is dispatching.",
      "time_occurred": "2026-03-05T00:00:00Z",
      "time_expected": "2026-03-04T09:00:00Z",
      "time_created": "2026-11-07T05:30:02Z",
      "suspension_reasons": [
        "DISPATCH_UNRESPONSIVE"
      ],
      "metadata": "Device properties changed, registration update successful. Reference XM2345TYUQ."
    }
  ],
  "time_updated": "2023-11-07T05:31:56Z",
  "time_created": "2023-11-07T05:31:56Z",
  "account_id": "acc_661677911f2197045e6cf1b1",
  "suspension_reasons": [
    "TELEMETRY_STALLED"
  ],
  "warnings": [
    "TELEMETRY_STALLED"
  ],
  "terms": {
    "rewards": [
      {
        "basis": "FIXED",
        "rate": 15,
        "period": "QUARTER"
      },
      {
        "basis": "DELIVERED_KWH",
        "rate": 0.35
      }
    ],
    "opt_out_policy": "ALLOWED",
    "notice_days": 30
  }
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

Authorizations

Authorization

string

header

required

Bearer token obtained from POST /auth/tokens.

Path Parameters

device_id

string

required

Flatpeak Device ID.

Example:

"dev_63a6087272941ef077a8fd3e"

Body

application/json

Enrolls a device in a VPP program.

program_id

string

required

Flatpeak VPP Program ID.

Example:

"vpr_6a1f8e375db9de605baadd46"

Response

VPP enrollment response.

A device's enrollment in a VPP program, with its lifecycle timeline. Ended enrollments are retained; at most one is in a non-terminal state at a time.

string

required

Flatpeak VPP Enrollment ID.

Example:

"enr_7c2f1a9e4b0d8f3a6e2c5d10"

object

enum<string>

default:vpp_enrollment

required

Object type.

Available options:

vpp_enrollment

Example:

"vpp_enrollment"

live_mode

boolean

required

true for live data, false for test data.

operator

object

required

The VPP operator that runs the program.

Show child attributes

program

object

required

The VPP program the device is enrolled in.

Show child attributes

device_id

string

required

Flatpeak Device ID of the enrolled device.

Example:

"dev_63a6087272941ef077a8fd3e"

location_id

string

required

Flatpeak Location ID of the device's location.

Example:

"loc_641b90b758fb8e6293716e40"

state_data_delayed

boolean

required

true when device state submissions have stalled beyond the device's required cadence.

Example:

false

device_meters_data_delayed

boolean

required

true when the device's own meter record submissions have stalled beyond the program's required cadence.

Example:

false

enrollment_state

enum<string>

required

The enrollment lifecycle state. enrollment_step gives the detail.

Value	Meaning
`PENDING`	Onboarding: consent, a connected tariff, telemetry, the dispatch test and approval
`ACTIVE`	Enrolled and dispatchable. `warnings` lists any non-critical issue
`SUSPENDED`	Not dispatchable until every reason in `suspension_reasons` clears
`LEAVING`	A request to leave is waiting for the VPP operator's approval. The device serves only the commitments it already has
`ENDED`	Unenrolled. Terminal
`REJECTED`	Ineligible, declined, or onboarding failed. Terminal

Available options:

PENDING,

ACTIVE,

SUSPENDED,

LEAVING,

ENDED,

REJECTED

Example:

"ACTIVE"

enrollment_step

enum<string>

required

The current step within enrollment_state, matching the timeline entry whose step_status is IN_PROGRESS.

Step	State	Meaning
`REQUESTED`	`PENDING`	The user asked to join
`AWAITING_CONSENT`	`PENDING`	Waiting for the consent scopes the program needs
`AWAITING_TARIFF`	`PENDING`	Waiting for a connected tariff at the device's location
`AWAITING_TELEMETRY`	`PENDING`	Waiting for the feeds the program requires
`TESTING_DISPATCH`	`PENDING`	Running the program's dispatch test
`AWAITING_APPROVAL`	`PENDING`	Waiting for the VPP operator's approval
`ACTIVE`	`ACTIVE`	Enrolled
`SUSPENDED`	`SUSPENDED`	Suspended
`UNENROLLING`	`LEAVING`	The user or the OEM asked to leave. The request waits for the VPP operator's approval
`UNENROLLED`	`ENDED`	Unenrolled
`INELIGIBLE`	`REJECTED`	The device does not qualify, or the VPP operator turned the request down
`FAILED`	`REJECTED`	Onboarding could not complete, for example a failed dispatch test

Available options:

REQUESTED,

AWAITING_CONSENT,

AWAITING_TARIFF,

AWAITING_TELEMETRY,

TESTING_DISPATCH,

AWAITING_APPROVAL,

ACTIVE,

SUSPENDED,

UNENROLLING,

UNENROLLED,

INELIGIBLE,

FAILED

Example:

"ACTIVE"

enrollment_state_timeline

VppEnrollmentTimelineEntry · object[]

required

Ordered lifecycle timeline. Render in array order, do not sort by date.

Minimum array length: 1

Show child attributes

time_updated

string<date-time>

required

Time the enrollment was last updated.

time_created

string<date-time>

required

Time the enrollment was created.

account_id

string

required

Flatpeak Account ID.

Example:

"acc_661677911f2197045e6cf1b1"

suspension_reasons

enum<string>[]

Why the enrollment is suspended. Present only when enrollment_state is SUSPENDED; contains at least one reason. Critical reasons suspend; the others appear in warnings instead.

Value	Meaning
`DISPATCH_UNRESPONSIVE`	The device is not acting on instructions
`CONSENT_REVOKED`	The user withdrew a consent scope the program requires. Critical
`TELEMETRY_STALLED`	A required feed is present but silent beyond its cadence
`USER_PAUSED`	Paused by the user. Critical

Minimum array length: 1

Available options:

DISPATCH_UNRESPONSIVE,

CONSENT_REVOKED,

TELEMETRY_STALLED,

USER_PAUSED

warnings

enum<string>[]

Non-critical issues on an active enrollment. Present only when enrollment_state is ACTIVE and an issue is open. The device stays dispatchable; a warning left unresolved past its grace period becomes a suspension reason.

Minimum array length: 1

Available options:

DISPATCH_UNRESPONSIVE,

CONSENT_REVOKED,

TELEMETRY_STALLED,

USER_PAUSED

terms

object

read-only

The program's terms as they stood when the user joined. Rewards are priced from this copy, and a later change to the program's terms does not alter it.

Show child attributes

Platform

Tariffs

VPP

Create a VPP enrollment

Authorizations

Path Parameters

Body

Response