# Programs

Endpoints related to incentivised charging programs.

## List vehicle compatibility for a program

 - [GET /programs/{program_id}/vehicle_compatibility](https://developers.ev.energy/ev.energy-api-v2/programs/get-programs-program_id-vehicle_compatibility.md): List vehicle compatibility records for a specific program.

Returns all active vehicle models that are supported by the given program.

## List programs

 - [GET /programs](https://developers.ev.energy/ev.energy-api-v2/programs/get-programs.md): By default, this endpoint returns all programs in our system and does not require authentication. The coordinates, postal_code and country_code query parameters can be used to narrow the list down to just programs eligible for particular locations. Coordinates and postal code searching are mutually exclusive and mixing the query parameters will result in a 400 error response.

If the client is authenticated as a specific user (either via Authorisation Code grant type or the EvEnergy-User header) it will return only programs that user is possibly eligible for, based on the location information we have for them.

## Retrieve a program

 - [GET /programs/{program_id}](https://developers.ev.energy/ev.energy-api-v2/programs/get-programs-program_id.md): Retrieve details for a single, specific program.

## List incentive schemes

 - [GET /incentive_schemes](https://developers.ev.energy/ev.energy-api-v2/programs/get-incentive_schemes.md): Returns a list of Incentive Schemes that the authenticated User is eligble for.

## Verify user

 - [POST /programs/{program_id}/user_verification](https://developers.ev.energy/ev.energy-api-v2/programs/post-programs-user-verification.md): Upload a user's utility account information for verification and account matching against the utility's customer data.

An endpoint to serve this data will be added in future.

## List program tiers

 - [GET /programs/{program_id}/tiers](https://developers.ev.energy/ev.energy-api-v2/programs/get-programs-program_id-tiers.md): List all selectable tiers under the given Program. Public read-only — no
authentication required. When the request is authenticated as a specific
user (Authorization Code grant, or Client Credentials with EvEnergy-User),
each tier's eligible field is populated with the user's eligibility result.
Anonymous or pure client-credentials requests receive eligible: null.

## Retrieve a program tier

 - [GET /programs/{program_id}/tiers/{tier_id}](https://developers.ev.energy/ev.energy-api-v2/programs/get-programs-program_id-tiers-tier_id.md): Retrieve a single tier nested under a Program. Public read-only. The
eligible field is per-user (see the list endpoint description).

## List participation agreement versions

 - [GET /programs/{program_id}/participation_agreement_versions](https://developers.ev.energy/ev.energy-api-v2/programs/get-programs-program_id-participation_agreement_versions.md): List versions of the Participation Agreement attached to the given Program.
Public read-only — no authentication required. Fetch the single currently
active version from the current sub-resource.

## Retrieve a participation agreement version

 - [GET /programs/{program_id}/participation_agreement_versions/{participation_agreement_version_id}](https://developers.ev.energy/ev.energy-api-v2/programs/get-programs-program_id-participation_agreement_versions-id.md): Retrieve a single Participation Agreement Version nested under a Program.
Public read-only.

## Retrieve the currently active participation agreement version

 - [GET /programs/{program_id}/participation_agreement_versions/current](https://developers.ev.energy/ev.energy-api-v2/programs/get-programs-program_id-participation_agreement_versions-current.md): Retrieve the currently active Participation Agreement Version — the
highest-numbered published version of the Program's agreement. current
is a magic value used in place of a version UID.

Public read-only. Returns 404 if the Program has no published version.

## Accept a participation agreement version

 - [POST /programs/{program_id}/participation_agreement_versions/{participation_agreement_version_id}/accept](https://developers.ev.energy/ev.energy-api-v2/programs/post-programs-program_id-participation_agreement_versions-id-accept.md): Record that the authenticated user has accepted the given Participation
Agreement Version, identified by its UID (e.g. the id returned by the
current sub-resource).

The request body must be an empty JSON object ({}). Sending any
additional fields returns 400 Bad Request. The success response is
201 Created with no body. The acceptance is idempotent — repeating the
call for the same (user, version) pair returns 201 without creating a
duplicate acceptance record.

Requires a user-grant access token (Authorization Code or Password). The
endpoint is not exposed to Client Credentials clients because acceptance
is intrinsically a per-user action.

## Post-enrollment verification

 - [POST /programs/{program_id}/post-enrollment-verification](https://developers.ev.energy/ev.energy-api-v2/programs/post-programs-post-enrollment-verification.md): Upload a user's post-enrollment verification data for account verification.

This endpoint validates data against the program's post-enrollment verification schema.