> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a VPP enrollment > Retrieves a VPP enrollment. ## OpenAPI ````yaml energy-api/reference/flatpeak-api-spec-energy.json GET /vpp-enrollments/{enrollment_id} openapi: 3.0.3 info: description: >- The Flatpeak Energy API connects energy hardware (batteries, EV chargers, vehicles, heat pumps, water heaters, solar and generators) to electricity prices, grid fees, and VPP programs. ## Create bearer token Obtain a bearer token from `POST /auth/tokens` using your `account_id` and `secret_key` via basic auth, then send it as `Authorization: Bearer ` on every request. ## Base URL `https://energy-api.flatpeak.com` ## Pagination List endpoints return a `list` envelope with `data`, `next_cursor`, and `url`. Page forward by passing `next_cursor` as `cursor` on the next request, until it is `null`. Cursors are opaque and bound to the endpoint and query parameters that issued them. ## Errors Every non-2xx response uses a standard error envelope with `object`, `type`, `code`, and `message`. Codes are machine-readable and safe to branch on. ## Money Monetary values are decimal numbers and are always paired with a `currency_code` (ISO 4217). Energy is expressed in kilowatt hours (kWh). ## Live vs test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Energy API termsOfService: https://flatpeak.com/legal contact: name: Technical Support email: support@flatpeak.com url: https://flatpeak.com/contact license: name: Apache 2.0 url: https://flatpeak.com/legal servers: - url: https://energy-api.flatpeak.com security: - bearerAuth: [] tags: - name: Authentication description: >- Exchange your account credentials for a bearer token to authenticate API requests. - name: Connect description: >- Create and retrieve Connect sessions. Connect drives the user journeys for tariff connection, VPP enrollment, and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). x-tariff-description: >- Create and retrieve Connect sessions. Connect drives the user journeys for tariff connection and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). - name: Users description: Create, retrieve, update, delete, and list users. - name: Locations description: Create, retrieve, update, delete, and list locations. - name: Devices description: >- Create, retrieve, update, delete and list devices; submit and retrieve their state; read and write their shared settings. - name: Meters description: Submit meter records and check batch status. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Prices description: Retrieve and audit calculated energy prices. - name: Costs description: Calculate the monetary cost of imported or exported energy. - name: Optimizations description: >- Rank the connected tariff to find the best times to consume or export energy, as inputs to your own scheduling. - name: Dispatch description: >- Fetch the VPP operator's instructions for a device, and confirm what the device will deliver. - name: Events description: Retrieve and list account events. - name: VPP Enrollments description: Create, retrieve and list VPP enrollments, and unenroll a device. - name: VPP Programs description: List VPP programs available to devices. - name: VPP Events description: >- VPP events committed by VPP operators, with your fleet's share and its per-device allocation. You can take over the allocation while it is open. - name: Operator groups description: >- Read-only views of the device groups VPP operators define. You see the groups that touch your fleet, and only your own devices in them. - name: Zones description: >- Network areas VPP operators define that touch your fleet. Read-only. You see only your own devices in them. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /vpp-enrollments/{enrollment_id}: parameters: - schema: type: string name: enrollment_id in: path required: true description: Flatpeak VPP Enrollment ID. get: tags: - VPP Enrollments summary: Retrieve a VPP enrollment description: Retrieves a VPP enrollment. operationId: get-vpp-enrollment parameters: [] responses: '200': $ref: '#/components/responses/VppEnrollment' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: responses: '401': description: '401 Unauthorized: authentication credentials are missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: '403 Forbidden: you do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '404 Not Found: the requested resource does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '429 Too Many Requests: the rate limit has been exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- 500 Internal Server Error: an unexpected error occurred. Safe to retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- 503 Service Unavailable: the service is temporarily down for maintenance. Retry after the indicated delay. content: application/json: schema: $ref: '#/components/schemas/Error' VppEnrollment: description: VPP enrollment response. content: application/json: schema: $ref: '#/components/schemas/VppEnrollment' schemas: VppEnrollment: type: object title: VppEnrollment additionalProperties: false description: >- 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. x-examples: Example 1: 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 device_id: dev_63a6087272941ef077a8fd3e location_id: loc_641b90b758fb8e6293716e40 enrollment_state: PENDING enrollment_step: AWAITING_APPROVAL state_data_delayed: false enrollment_state_timeline: - state: PENDING step: REQUESTED step_status: COMPLETE description: We've received your request to join the program. time_occurred: '2026-03-01T09:00:00Z' time_expected: null time_created: '2026-03-01T09:00:00Z' - state: PENDING step: AWAITING_CONSENT step_status: COMPLETE description: We need your permission to manage your device. time_occurred: '2026-03-01T09:00:05Z' time_expected: null time_created: '2026-03-01T09:00:05Z' - state: PENDING step: AWAITING_TELEMETRY step_status: COMPLETE description: We're waiting to receive data from your device. time_occurred: '2026-03-01T09:02:11Z' time_expected: null time_created: '2026-03-01T09:02:11Z' - state: PENDING step: TESTING_DISPATCH step_status: PENDING description: >- We're running a short test to check your device responds to instructions. time_occurred: null time_expected: null time_created: '2026-03-01T09:30:45Z' - state: PENDING step: AWAITING_APPROVAL step_status: PENDING description: We're registering your device with the program. time_occurred: null time_expected: '2026-03-02T10:00:00Z' time_created: '2026-03-01T09:30:45Z' - state: ACTIVE step: ACTIVE step_status: PENDING description: Your device is active and taking part in the program. time_occurred: null time_expected: '2026-03-05T00:00:00Z' time_created: '2026-03-01T09:30:45Z' time_updated: '2026-03-01T09:30:45Z' time_created: '2026-03-01T09:00:00Z' account_id: acc_661677911f2197045e6cf1b1 device_meters_data_delayed: false terms: rewards: - basis: FIXED rate: 15 period: QUARTER - basis: DELIVERED_KWH rate: 0.35 opt_out_policy: ALLOWED notice_days: 30 properties: id: type: string description: Flatpeak VPP Enrollment ID. example: enr_7c2f1a9e4b0d8f3a6e2c5d10 object: type: string description: Object type. example: vpp_enrollment enum: - vpp_enrollment default: vpp_enrollment live_mode: type: boolean description: '`true` for live data, `false` for test data.' operator: type: object description: The VPP operator that runs the program. required: - id - display_name - logo_url - support_email properties: id: type: string example: opr_8587fa49c7e5297ccc6c57e5 description: Flatpeak ID of the VPP operator. display_name: type: string example: Pick description: VPP operator display name. logo_url: type: string example: https://s.flatpeak.com/83b06a60e38c2.png description: VPP operator logo URL. support_email: type: string example: help@pick.com description: VPP operator support email. program: type: object required: - id - display_name - url properties: id: type: string example: vpr_6a1f8e375db9de605baadd46 description: Flatpeak VPP Program ID. display_name: type: string example: Community Powershare description: VPP program display name. url: type: string example: https://pick.com/programs/community-powershare description: VPP program information URL. dispatch_test_required: type: boolean readOnly: true example: true description: >- `true` when enrollment includes a dispatch test: Flatpeak issues a `TEST` event, and the device must deliver it before approval. `false` when the step is skipped. managed: type: boolean example: false description: >- `true` for a managed tariff: the VPP operator runs the device under this program with binding plans, and it replaces the user's tariff. description: The VPP program the device is enrolled in. device_id: type: string description: Flatpeak Device ID of the enrolled device. example: dev_63a6087272941ef077a8fd3e location_id: type: string description: Flatpeak Location ID of the device's location. example: loc_641b90b758fb8e6293716e40 state_data_delayed: type: boolean description: >- `true` when device state submissions have stalled beyond the device's required cadence. example: false device_meters_data_delayed: type: boolean description: >- `true` when the device's own meter record submissions have stalled beyond the program's required cadence. example: false suspension_reasons: type: array description: >- 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 | uniqueItems: true minItems: 1 items: type: string enum: - DISPATCH_UNRESPONSIVE - CONSENT_REVOKED - TELEMETRY_STALLED - USER_PAUSED example: TELEMETRY_STALLED warnings: type: array uniqueItems: true minItems: 1 items: type: string enum: - DISPATCH_UNRESPONSIVE - CONSENT_REVOKED - TELEMETRY_STALLED - USER_PAUSED example: TELEMETRY_STALLED description: >- 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. enrollment_state: type: string enum: - PENDING - ACTIVE - SUSPENDED - LEAVING - ENDED - REJECTED description: >- 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 | example: ACTIVE enrollment_step: type: string enum: - REQUESTED - AWAITING_CONSENT - AWAITING_TARIFF - AWAITING_TELEMETRY - TESTING_DISPATCH - AWAITING_APPROVAL - ACTIVE - SUSPENDED - UNENROLLING - UNENROLLED - INELIGIBLE - FAILED description: >- 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 | example: ACTIVE enrollment_state_timeline: type: array description: >- Ordered lifecycle timeline. Render in array order, do not sort by date. minItems: 1 items: $ref: '#/components/schemas/VppEnrollmentTimelineEntry' terms: type: object description: >- 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. properties: rewards: type: array description: What the user is paid. Each `basis` appears at most once. example: - basis: FIXED rate: 15 period: QUARTER - basis: DELIVERED_KWH rate: 0.35 items: type: object required: - basis - rate properties: basis: type: string enum: - FIXED - EVENT - DELIVERED_KWH - COMMITTED_KWH example: DELIVERED_KWH description: >- What `rate` is paid for. | Value | `rate` is paid | | :--- | :--- | | `FIXED` | Once per `period`, by calendar period, pro-rated by the days the enrollment is `ACTIVE` | | `EVENT` | Per VPP event the device delivers in full | | `DELIVERED_KWH` | Per kWh delivered, from the device's meter records | | `COMMITTED_KWH` | Per kWh of the device's locked share of a VPP event, whatever the device then delivers. Nothing for a commitment the user opted out of | rate: type: number example: 0.35 description: >- Amount paid per unit of `basis`, in the program's `currency_code`, in large currency units. period: type: string enum: - MONTH - QUARTER - YEAR example: QUARTER description: >- Period a `FIXED` reward is paid for. Required when `basis` is `FIXED`, and not used otherwise. opt_out_policy: type: string enum: - ALLOWED - ALLOWED_BEFORE_LOCK - NOT_ALLOWED example: ALLOWED description: >- Whether users may skip individual VPP events. | Value | Meaning | | :--- | :--- | | `ALLOWED` | Default. Any scheduled or active VPP event. Skipped intervals are recorded as `OPTED_OUT`. | | `ALLOWED_BEFORE_LOCK` | Only until the allocation locks. | | `NOT_ALLOWED` | No per-event opt-out. Users can still unenroll. | notice_days: type: integer example: 30 description: >- Maximum number of days leaving may take once the user is enrolled. A request to leave that the VPP operator has not approved ends after this many days. Shown to the user before they join and when they leave. readOnly: true time_updated: type: string format: date-time description: Time the enrollment was last updated. time_created: type: string format: date-time description: Time the enrollment was created. account_id: type: string example: acc_661677911f2197045e6cf1b1 description: Flatpeak Account ID. required: - id - object - live_mode - operator - program - device_id - location_id - state_data_delayed - device_meters_data_delayed - enrollment_state - enrollment_step - enrollment_state_timeline - time_updated - time_created - account_id Error: type: object description: Standard error envelope returned by every non-2xx response. required: - object - type - code - message properties: object: type: string enum: - error default: error description: Object type. type: type: string description: High-level error category. example: invalid_request code: type: string description: Machine-readable error code, safe to branch on. example: not_found message: type: string description: Human-readable description of the error. example: The requested resource could not be found. context: type: string description: Optional originating context, for example `api.price_get`. example: api.price_get live_mode: type: boolean description: Whether the error occurred against live or test data. time_created: type: string format: date-time description: Time the error was generated (RFC 3339). example: '2026-01-01T00:00:00Z' VppEnrollmentTimelineEntry: type: object additionalProperties: false description: A single entry in the enrollment lifecycle timeline. properties: state: type: string enum: - PENDING - ACTIVE - SUSPENDED - LEAVING - ENDED - REJECTED description: The enrollment state this entry belongs to. example: ACTIVE step: type: string enum: - REQUESTED - AWAITING_CONSENT - AWAITING_TARIFF - AWAITING_TELEMETRY - TESTING_DISPATCH - AWAITING_APPROVAL - ACTIVE - SUSPENDED - UNENROLLING - UNENROLLED - INELIGIBLE - FAILED description: >- The step this entry represents. See `enrollment_step` on the enrollment for every value. example: ACTIVE step_status: type: string description: |- Exactly one entry is `IN_PROGRESS`. | Value | Meaning | | :--- | :--- | | `COMPLETE` | Past step | | `IN_PROGRESS` | Current step | | `PENDING` | Queued step | | `SKIPPED` | Bypassed step | | `FAILED` | Step could not complete | enum: - COMPLETE - IN_PROGRESS - PENDING - SKIPPED - FAILED example: COMPLETE description: type: string description: Human-readable description of the step, suitable to show the user. example: Your device is dispatching. time_occurred: type: string format: date-time description: >- Time the step was reached. Set for `COMPLETE` and `IN_PROGRESS`, `null` otherwise. example: '2026-03-05T00:00:00Z' nullable: true time_expected: type: string format: date-time description: >- Estimated time a `PENDING` step will be reached. `null` when it cannot be estimated or the step has been reached. example: '2026-03-04T09:00:00Z' nullable: true suspension_reasons: type: array description: >- Suspension reasons at this step. Present only when `step` is `SUSPENDED`; when present, contains at least one reason. uniqueItems: true minItems: 1 items: type: string enum: - DISPATCH_UNRESPONSIVE - CONSENT_REVOKED - TELEMETRY_STALLED - USER_PAUSED metadata: type: string example: >- Device properties changed, registration update successful. Reference XM2345TYUQ. description: Description of the event. time_created: type: string format: date-time example: '2026-11-07T05:30:02Z' description: Time when the entry was created. required: - state - step - step_status - description - time_occurred - time_expected - time_created title: VppEnrollmentTimelineEntry securitySchemes: bearerAuth: type: http scheme: bearer description: Bearer token obtained from POST /auth/tokens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.