# Participate Energy Design API v2

This is the plain Markdown copy of the Design API v2 documentation, for AI coding assistants and offline reading. The interactive reference is at https://api.participate.energy/docs/design/v2/ and the OpenAPI file is at https://api.participate.energy/docs/design/v2/openapi.yaml.

The Participate Energy (PE) Design API lets proposal and design software price PE leases and send signed contracts to PE. Your users are PE installers. With this API, your software can do these tasks for an installer:

- Read the reference data PE uses: the Approved Vendor List (AVL), the installer's Safe Harbor opportunities, the installer's active states and the utilities of a ZIP code.
- Check whether a site is eligible, and check Domestic Content, Energy Community and the lease sales tax rate.
- Price a PE lease, and price a PE lease with a Sungage loan.
- Create a PE project by uploading the signed customer contract.
- Read the status of the projects that you created, and get webhooks when PE approves the Inspection Complete (IC) and Project Complete (PC) milestones.

**To price a project and send its contract**, call the endpoints in this order:

1. Read the AVL with `GET /avl`. For a Safe Harbor project, also read the opportunity's custom AVL with `GET /safe-harbor/opportunities/{opportunityId}/avl`.
2. Match the design's equipment to AVL SKUs in your own system.
3. Check the site with `POST /eligibility`, Domestic Content and FEOC with `POST /tax-credits/domestic-content`, Energy Community with `POST /tax-credits/energy-community`, and the sales tax rate with `POST /sales-tax`.
4. Confirm FEOC. PE does not accept a project that does not meet the FEOC threshold for its construction year (`feoc.pv.eligible` and `feoc.storage.eligible` must be `true` for each kind the project includes).
5. Price the PE lease with `POST /pricing/lease`, or PE with a Sungage loan with `POST /pricing/sungage`.
6. Build the contract, have the customer sign it, and send it with a contract upload (`POST /contract-uploads`). Contract e-sign through the API is coming soon.

## What changed in 2.2

Version 2.2 adds input guardrails. A request that is very likely wrong (a unit mix-up, a wrong field, an impossible value) is now refused with a clear error, or priced with a warning. A correct 2.1 request prices the same in 2.2.

- `epcAmount` must be from 1,000 to 500,000 US dollars ([`EPC_OUT_OF_RANGE`](#error-EPC_OUT_OF_RANGE)). The message says when the amount looks like cents or a $/W price. The limit was 10,000,000 before.
- `POST /pricing/lease` and `POST /pricing/sungage` take a new optional `systemSizeKw` (the DC size in kW). With it, the EPC must be from $1 to $10 per watt on a `solar_only` system, and at least $1 per watt on `solar_battery` (the EPC also pays for the battery); `battery_only` has no per watt check ([`EPC_PER_WATT_OUT_OF_RANGE`](#error-EPC_PER_WATT_OUT_OF_RANGE)). The size must be from 0.5 to 250 kW ([`SYSTEM_SIZE_OUT_OF_RANGE`](#error-SYSTEM_SIZE_OUT_OF_RANGE)); a value that looks like watts, such as 7200, is [`SYSTEM_SIZE_LOOKS_LIKE_WATTS`](#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS). The API never converts units. `systemSizeKw` does not change the numbers.
- `contractDate` must be from one year before today to 90 days after today ([`CONTRACT_DATE_OUT_OF_RANGE`](#error-CONTRACT_DATE_OUT_OF_RANGE)). For a Hawaii site it must also be on or after 2026-07-03, the date the Hawaii RETITC stopped being included ([`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`](#error-CONTRACT_DATE_BEFORE_RETITC_CUTOFF)).
- `energyCommunity: true` is checked against PE's Energy Community lookup for the site address. When the address does not qualify, the quote is priced with `energyCommunity` false and has an `ENERGY_COMMUNITY_NOT_CONFIRMED` warning. When the lookup cannot run, the quote uses `true` and has an `ENERGY_COMMUNITY_NOT_VERIFIED` warning. `"auto"` and `false` work as before.
- An installer-managed incentive must be less than the EPC, and a quote never has a negative Net Amount Due ([`INCENTIVE_OUT_OF_RANGE`](#error-INCENTIVE_OUT_OF_RANGE)). A non-zero `includedIncentive.amount` with type `none` is now `VALIDATION_FAILED`; before, PE ignored it. An amount of `0` with type `none` is accepted.
- A `battery_only` quote takes no roofing cost ([`ROOFING_COST_NOT_APPLICABLE`](#error-ROOFING_COST_NOT_APPLICABLE)). A roofing cost above the EPC is a `ROOFING_COST_HIGH` warning. A flag that does not apply to the system type (`storageDomesticContent` on `solar_only`, `pvDomesticContent` on `battery_only`, `existingSolarOnProperty` on a system with solar) is a `FIELD_NOT_APPLICABLE` warning. A warning can name its `field`.
- `insuranceOption` also accepts the strings "1", "2" and "3", and `dcBonusRecipient` accepts any case. The canonical forms are the number and lower case; `inputsEcho` shows them. `inputsEcho` also has `systemSizeKw` (null when not sent).
- A site address whose street is a PO Box (PO Box, P.O. Box, Post Office Box, POB, P.O.B. or PMB) is refused with [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX) on every endpoint that takes a site address.
- `POST /sales-tax`: `netAmountDue` must be from 1,000 to 500,000 US dollars ([`AMOUNT_OUT_OF_RANGE`](#error-AMOUNT_OUT_OF_RANGE)); `0` counts as left out (the rate only), and a state where PE does not operate is [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED).
- `POST /sales-tax` and `POST /tax-credits/energy-community`: `resolvedAddress.mismatches` lists each field (`zipCode`, `city`, `stateCode`) where Google's address differs from the address you sent. In `POST /sales-tax`, a mismatch sets `jurisdiction.lowConfidence`. The Energy Community check, and the sales tax check in Colorado, accept a different ZIP code only when Google placed the same house number; otherwise they return `ADDRESS_NOT_FOUND`.
- A ZIP+4 is accepted wherever a ZIP code is, also in `GET /utilities`; PE uses the first 5 digits. A 4-digit ZIP code gets a hint that a leading zero may have been dropped.
- The ZIP code 00000 (or 00000 with a +4) is refused with [`VALIDATION_FAILED`](#error-VALIDATION_FAILED) wherever a ZIP code is taken, also in `GET /utilities`: it is no US ZIP code. Send the real ZIP code. `POB` and `P.O.B.` are PO Boxes too ([`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX)).
- `POST /tax-credits/domestic-content`: a SKU sent with the wrong category is [`EQUIPMENT_CATEGORY_MISMATCH`](#error-EQUIPMENT_CATEGORY_MISMATCH) (it was `EQUIPMENT_NOT_ON_AVL`). A `pv_module` or `pv_combo` line with more than 500 units is [`EQUIPMENT_QUANTITY_OUT_OF_RANGE`](#error-EQUIPMENT_QUANTITY_OUT_OF_RANGE). A missing `quantity` is 1, and `items` shows it.
- `GET /pricing/sungage/products`: a code that is not a US state is `VALIDATION_FAILED`, and a state where PE does not operate is `STATE_NOT_SUPPORTED`. Both were `SUNGAGE_UNAVAILABLE` (503) before.
- `GET /states` takes no query parameters (`UNKNOWN_FIELD`), and `enabledProducts` lists only the products you can upload (Synthetic Cash).
- Contract uploads: the upload URL now requires the exact `sizeBytes` you declared (`x-goog-content-length-range` is `sizeBytes,sizeBytes`), and submit refuses a stored file of another size ([`UPLOAD_SIZE_MISMATCH`](#error-UPLOAD_SIZE_MISMATCH)).
- Error details are clearer. A field's own rule is the `issue` (for example "contractDate must be YYYY-MM-DD"). A field that takes more than one form lists the forms in `expected` (`true | false | "auto"`). A near miss has `didYouMean`: an unknown field such as `zip`, `epc_amount` or `q`, or a value such as `"AUTO"`. Some details also have a `hint`.
- The `Authorization` scheme name is case-insensitive: `bearer` works like `Bearer`.
- `GET /projects/by-vendor-id` without an id is `ROUTE_NOT_FOUND`. A `RESOURCE_NOT_FOUND` for a project says in `details` when you sent an uploadId as a projectId, or when your upload has no project yet.

## What changed in 2.1

- `GET /utilities` lists the utilities of a ZIP code. Send `zipCode` (5 digits, or ZIP+4: PE uses the first 5 digits). The old `GET /utilities/{stateCode}` returns 410 `UTILITY_LIST_BY_STATE_RETIRED`.
- `POST /tax-credits/domestic-content` also reports Foreign Entity of Concern (FEOC) compliance: a `feoc` block and `items[].feocPercent`. The response `year` is now the year that set the thresholds (the BOC year when `thresholdBasis` is `boc`).
- `POST /tax-credits/energy-community` resolves the site address with Google Maps and returns `resolvedAddress`.
- A new endpoint, `POST /sales-tax`, returns the lease sales tax rate for a site address. It also resolves the address with Google Maps and returns `resolvedAddress`.
- `POST /tax-credits/energy-community`, and `POST /sales-tax` in Colorado, need a street address that Google can place: a street number and a street. Outside Colorado, `POST /sales-tax` also accepts a match where Google places only the street. That response has `resolvedAddress.precision: "street"` and `jurisdiction.lowConfidence: true`. When Google finds only an imprecise match, the API returns `ADDRESS_NOT_FOUND` and `details[0].closestMatch` shows the address that Google found.
- When the Google service is not available, these two endpoints return the new error `ADDRESS_LOOKUP_UNAVAILABLE` (503). Send the same request again later.
- In `POST /sales-tax`, `jurisdiction.lowConfidence` is true when the ZIP code has more than one rate and PE used the most common rate, when Google only partially matched the address, or when Google placed only the street.

## Pricing never creates a project

A price quote never creates a PE project. A price quote never returns a PE Project ID. The `quoteId` in a pricing response is for your logs only. PE does not store it.

A PE Project ID exists only after a contract upload creates a project. Read it from `project.projectId` in `GET /contract-uploads/{uploadId}` when the outcome is `project_created`. Do not show a PE Project ID to your users before that.

## Quick start

Do these steps in the Test environment first. PE sends you Test client credentials and a connection code for "Phobos Test Org", PE's test installer, in your onboarding email. You can start at once.

1. **Exchange the connection code for a grant.** Send your client credentials with HTTP Basic authentication. Keep the `grantId` from the response. It does not expire.

   ```bash
   curl https://api.participate.energy/v2/design/connections/exchange \
     -u "$PE_CLIENT_ID:$PE_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"connectionCode": "pec_..."}'
   ```

2. **Get an access token.** A token lasts 60 minutes. Get a new token when it expires.

   ```bash
   curl https://api.participate.energy/v2/design/oauth/token \
     -u "$PE_CLIENT_ID:$PE_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"grantType": "client_credentials", "grantId": "grt_..."}'
   ```

3. **Call ping.** The response shows the installer name, the environment and your scopes.

   ```bash
   curl https://api.participate.energy/v2/design/ping \
     -H "Authorization: Bearer $PE_ACCESS_TOKEN"
   ```

4. **Price a lease.** See `POST /pricing/lease`.
5. **Upload a test contract.** See the Contract uploads section. In the Test environment you choose the outcome with `sandboxScenario`.

At the same time, contact your installer customers. Ask each installer to create a connection code for you in the Installer Portal, under Tools > Integrations. PE wants this early engagement. Do not wait until your build is complete. A connection works in the Test environment and in production, so you can test with real installers before you go live.

## Actors and the connection flow

These are the actors:

- **PE operations** issues your client credentials and turns on your integration for each installer.
- **You, the vendor,** hold the client credentials. Your software calls the API.
- **The installer administrator** creates a connection code for your company in the Installer Portal. The code gives your company access to that installer's data, with the scopes the administrator selects.
- **The sales rep** is the installer's user who does the work in your software. You send the rep's email in the `X-PE-Actor-Email` header.

These are the credentials and ids:

| Item | Format | Lifetime | Who has it |
|---|---|---|---|
| Client ID | `dc_test_` or `dc_live_` and 24 letters and digits | 12 months | You |
| Client secret | `dcs_test_` or `dcs_live_` and 40 letters and digits | 12 months | You. PE shows it once and stores only a hash. |
| Connection code | `pec_` and 26 characters | 72 hours, one use | The installer gives it to you |
| Grant ID | `grt_` and 20 letters and digits | Until the installer, you or PE revokes it | You |
| Access token | A signed JWT | 60 minutes | You |

A grant connects one vendor to one installer, with a set of scopes. You have at most one active grant for each installer. When you exchange a new code for the same installer, PE revokes the old grant.

```text
 PE operations         You (vendor)            Installer admin             Design API
      |                     |                         |                          |
      | 1. Client ID and    |                         |                          |
      |    client secret    |                         |                          |
      |-------------------->|                         |                          |
      |                     | 2. Ask the installer    |                          |
      |                     |    to connect           |                          |
      |                     |------------------------>|                          |
      | 3. Turn on your integration for the installer |                          |
      |---------------------------------------------->|                          |
      |                     |                         | 4. Installer Portal:     |
      |                     |                         |    Tools > Integrations, |
      |                     |                         |    create a code         |
      |                     | 5. Connection code      |                          |
      |                     |    (pec_...)            |                          |
      |                     |<------------------------|                          |
      |                     | 6. POST /connections/exchange                      |
      |                     |    (code and client credentials)                   |
      |                     |--------------------------------------------------->|
      |                     |    grantId (grt_...)                               |
      |                     |<---------------------------------------------------|
      |                     | 7. POST /oauth/token                               |
      |                     |    (client credentials and grantId)                |
      |                     |--------------------------------------------------->|
      |                     |    accessToken (60 minutes)                        |
      |                     |<---------------------------------------------------|
      |                     | 8. API calls with Authorization: Bearer <token>    |
      |                     |--------------------------------------------------->|
```

Each access token is for one vendor, one installer (through the grant) and one environment (through the client credential). To work for many installers, keep one grant for each installer and get a token for each grant.

PE checks your client credential, the grant and your company status on every request. When an installer or PE revokes access, the change takes effect within 60 seconds. After a grant is revoked, the projects stay with the installer, and you can no longer read them.

## Authentication

Send `Authorization: Bearer <accessToken>` on every call except `POST /oauth/token` and `POST /connections/exchange`.

`POST /oauth/token` and `POST /connections/exchange` take your client credentials. Send them with HTTP Basic authentication (`-u clientId:clientSecret`) or as `clientId` and `clientSecret` in the body. These two endpoints accept a JSON body or a form body (`application/x-www-form-urlencoded`).

The token request uses the OAuth 2.0 client credentials grant with one extra field: `grantId`. It names the installer connection. `POST /oauth/token` also accepts the standard OAuth names `grant_type`, `client_id`, `client_secret` and `grant_id`. All other endpoints use camelCase names only.

The token response is in the PE envelope: read the token from `data.accessToken`. Cache the token and use it until shortly before `data.expiresIn` seconds pass.

The scopes of a token are the scopes that both your client credential and the grant allow. If a call needs a scope that the token does not have, the API returns `SCOPE_NOT_GRANTED`.

Keep the client secret in a secret manager. Never put it in a browser or a mobile app. Call the API from your servers only. The API does not support CORS.

## Environments

The environment comes from your client credential. A `dc_test_` credential gives Test tokens. A `dc_live_` credential gives production tokens. The base URL is the same for both.

- **Test.** Writes go to a separate sandbox. They never reach PE operations. No PE reviewer sees a test contract, and no test project appears in PE's systems. Contract review is simulated: you choose the outcome with `sandboxScenario`. Test files are deleted after 30 days. Test projects and uploads are deleted after 90 days.
- **Production.** Writes create real projects. PE reviews every contract.
- **Reference data is live in both environments.** The AVL, Safe Harbor opportunities, states, utilities, tax rates, eligibility rules and the Energy Community data are PE's production data. A Test price quote returns the same numbers as a production quote.
- **Sungage.** Test Sungage calls go to PE's Sungage sandbox account. Production calls go to the installer's own Sungage account.
- **The environments are separate.** A Test token never sees a production project or upload, and a production token never sees a Test one. The API returns `RESOURCE_NOT_FOUND` for these.

PE issues production credentials after you make at least one successful Test call for each scope you need. Tell PE when every scope works.

## Scopes

| Scope | What it allows |
|---|---|
| `avl:read` | Read the Approved Vendor List (AVL), an installer's Safe Harbor opportunities and their custom AVL items, the installer's active states and utilities. |
| `eligibility:read` | Check whether an address is eligible, and check Domestic Content, Energy Community and the lease sales tax rate. |
| `pricing:lease` | Price a Participate Energy lease for an installer's customer. |
| `pricing:sungage` | Price a Participate Energy lease with a Sungage loan, for installers in the PE and Sungage program. |
| `projects:create` | Create projects by uploading signed customer contracts. |
| `projects:read` | Read the status of projects and contract uploads you created. |
| `webhooks:manage` | Register a webhook endpoint and receive IC and PC approval events for projects you created. |

`POST /oauth/token`, `POST /connections/exchange`, `GET /grant`, `DELETE /grant` and `GET /ping` need no scope. `POST /sandbox/projects/{projectId}/simulate` needs `projects:read` and a Test token.

## The actor header

Send the email of the installer's sales rep in the `X-PE-Actor-Email` header. The header is for attribution. It does not authenticate the call.

- The header is required on `POST /contract-uploads`, `GET /pricing/sungage/products` and `POST /pricing/sungage`.
- The header is optional on all other endpoints. When you send it, PE checks it.
- PE accepts the email when it belongs to an active user of the installer (or of an organization below the installer), or when its domain is one of the installer's allowed domains. Otherwise the API returns `ACTOR_NOT_ON_ROSTER`.
- For a production contract upload, PE records the email as the sales rep of the project.

## Requests and responses

- The base URL is `https://api.participate.energy/v2/design`.
- Send JSON with `Content-Type: application/json`. The body limit is 1 MiB.
- Field names are camelCase.
- PE rejects unknown fields with `UNKNOWN_FIELD`. The `details` list names each unknown field.
- Money is a JSON number in US dollars, rounded to cents. Rates are fractions (`0.0825` is 8.25%), except where a field name says percent.
- Dates are `YYYY-MM-DD`. Timestamps are ISO 8601 in UTC.
- A success response is `{"data": ..., "meta": {"requestId", "environment", "timestamp"}}`.
- An error response is `{"error": {"code", "message", "retryable", "details", "docsUrl"}, "meta": {...}}`. See Errors.
- Every response has an `X-Request-Id` header. You can send your own `X-Request-Id` (1 to 64 letters, digits, `.`, `_` or `-`). PE then uses your value. Otherwise PE makes one that starts with `req_`.
- Every response has `Cache-Control: private, no-store`.
- Your client must accept new optional response fields and new enum values.
- PE does not support an `Idempotency-Key` header. A retried `POST /contract-uploads` with the same `vendorProjectId` does not make a second upload: it returns `DUPLICATE_VENDOR_PROJECT_ID` with the first `uploadId` in `details`.

## Rate limits

| Limit | Value | Applies to |
|---|---|---|
| Reads | 120 per minute | Each client credential: GET calls, eligibility and tax credit checks |
| Writes | 30 per minute | Each client credential: contract uploads, webhook changes, `DELETE /grant`, simulate |
| Pricing | 60 per minute | Each client credential: `POST /pricing/lease`, `GET /pricing/sungage/products`, `POST /pricing/sungage` |
| Credential calls | 30 per minute | Each IP address: `POST /oauth/token` and `POST /connections/exchange` |
| Contract uploads | 200 per day (production), 50 per day (Test) | Each grant. The day is the UTC day. |

When you reach a limit, the API returns HTTP 429 with `RATE_LIMITED` or `DAILY_QUOTA_EXCEEDED`. The `Retry-After` header gives the seconds to wait. The error `details` give `limit`, `window` and `resetAt`.

## Versioning

The version is in the path: `/v2/design`. In v2, PE can add endpoints, optional request fields, response fields, enum values, warning codes and error codes. These changes do not break a client that follows this guide. PE does not remove or rename a field in v2.

A breaking change comes in a new version with a new path. PE tells you by email before it retires a version, and runs both versions in parallel during the change.

## Support

Email raceway.support@participate.energy. Include the request id (`X-Request-Id`), the time, the endpoint and the error code. Never send a client secret, an access token or a connection code.

## Build with an AI assistant

This documentation is also available as files for AI coding assistants:

- OpenAPI (YAML): https://api.participate.energy/docs/design/v2/openapi.yaml
- OpenAPI (JSON): https://api.participate.energy/docs/design/v2/openapi.json
- This guide as plain Markdown: https://api.participate.energy/docs/design/v2/guide.md

Give the assistant the OpenAPI file and the guide. Ask it to follow the guide: keep the client secret on the server, cache tokens, poll uploads with backoff, verify webhook signatures and handle every error code. Test all the generated code in the Test environment before you use production credentials.

## Endpoints

| Method and path | operationId | Scope | Summary |
|---|---|---|---|
| `POST /oauth/token` | `createAccessToken` | none | Get an access token |
| `POST /connections/exchange` | `exchangeConnectionCode` | none | Exchange a connection code for a grant |
| `GET /grant` | `getGrant` | none | Read the grant |
| `DELETE /grant` | `revokeGrant` | none | Revoke the grant |
| `GET /ping` | `ping` | none | Check the token |
| `GET /avl` | `listAvl` | `avl:read` | List AVL equipment |
| `GET /safe-harbor/opportunities` | `listSafeHarborOpportunities` | `avl:read` | List Safe Harbor opportunities |
| `GET /safe-harbor/opportunities/{opportunityId}/avl` | `listSafeHarborOpportunityAvl` | `avl:read` | List an opportunity's custom AVL |
| `GET /states` | `listStates` | `avl:read` | List the installer's states |
| `GET /utilities` | `listUtilitiesByZip` | `avl:read` | List the utilities of a ZIP code |
| `GET /utilities/{stateCode}` | `listUtilities` | `avl:read` | Retired in 2.1: returns 410 `UTILITY_LIST_BY_STATE_RETIRED` |
| `POST /eligibility` | `checkEligibility` | `eligibility:read` | Check site eligibility |
| `POST /tax-credits/domestic-content` | `checkDomesticContent` | `eligibility:read` | Check Domestic Content |
| `POST /tax-credits/energy-community` | `checkEnergyCommunity` | `eligibility:read` | Check Energy Community |
| `POST /sales-tax` | `checkSalesTax` | `eligibility:read` | Read the lease sales tax rate |
| `POST /pricing/lease` | `priceLease` | `pricing:lease` | Price a PE lease |
| `GET /pricing/sungage/products` | `listSungageProducts` | `pricing:sungage` | List Sungage products |
| `POST /pricing/sungage` | `priceSungage` | `pricing:sungage` | Price a PE lease with a Sungage loan |
| `POST /contract-uploads` | `createContractUpload` | `projects:create` | Create a contract upload |
| `POST /contract-uploads/{uploadId}/submit` | `submitContractUpload` | `projects:create` | Submit a contract upload |
| `GET /contract-uploads/{uploadId}` | `getContractUpload` | `projects:read` | Read a contract upload |
| `GET /projects/by-vendor-id/{vendorProjectId}` | `getProjectByVendorId` | `projects:read` | Read a project by your id |
| `GET /projects/{projectId}` | `getProject` | `projects:read` | Read a project |
| `PUT /webhooks` | `setWebhook` | `webhooks:manage` | Set the webhook URL |
| `GET /webhooks` | `getWebhook` | `webhooks:manage` | Read the webhook URL |
| `DELETE /webhooks` | `deleteWebhook` | `webhooks:manage` | Delete the webhook URL |
| `POST /webhooks/rotate-secret` | `rotateWebhookSecret` | `webhooks:manage` | Rotate the signing secret |
| `POST /webhooks/test` | `testWebhook` | `webhooks:manage` | Send a test event |
| `POST /sandbox/projects/{projectId}/simulate` | `simulateProjectEvent` | `projects:read` | Simulate a project event |

## Authentication

Exchange an installer's connection code for a grant, and get access tokens. These two endpoints take your client credentials (HTTP Basic or body fields). They do not take a bearer token. Each IP address can make 30 calls per minute to them.

Exchange each connection code once. Store the `grantId` with the installer's record in your system. Then get a token for that grant when you need one. A token lasts 60 minutes.

## Connection

Read or end the connection (grant) behind your token, and check that your token works.

Call `GET /ping` after you get a new credential or a new grant, and when a call fails for an unknown reason. Call `DELETE /grant` when the installer stops using your software. The installer can also revoke the connection in the Installer Portal, and PE can revoke it. After a revoke, calls with the grant return `GRANT_REVOKED`.

## AVL and reference data

Read the reference data you need to build a quote. This data is PE's production data in both environments.

- `GET /avl` lists the equipment on PE's Approved Vendor List with its Domestic Content values. Page with `limit` and `nextCursor`. A cursor is valid only for the AVL version that issued it. When PE publishes a new AVL version, start again without a cursor.
- `GET /safe-harbor/opportunities` lists the installer's Safe Harbor opportunities that carry a deduction in pricing (Strategy D, active, with a unit cost). Use `opportunityId` in `safeHarbor.opportunityId` of a pricing request.
- `GET /safe-harbor/opportunities/{opportunityId}/avl` lists the custom AVL items of one opportunity.
- `GET /states` lists the states where the installer is active and PE operates, and the PE products enabled for the installer that you can upload (Synthetic Cash). It takes no query parameters.
- `GET /utilities?zipCode=` lists the utilities that serve a ZIP code.

## Eligibility

Check a site before you price it, and check the tax credit facts that change the lease factor.

`POST /eligibility` runs every rule and returns one entry in `checks` for each rule. A failed rule is a check with `result: "fail"` and an error `code`. It is not an error response. `eligible` is `true` when no check failed. A check with `result: "not_evaluated"` needs a PE review. It does not make the site ineligible.

| Check | Rule |
|---|---|
| `state` | PE operates in the state. |
| `installer_state` | The installer is active in the state. PE checks it only when the state passes. |
| `product` | The PE lease (Synthetic Cash) is enabled for the installer. |
| `utility` | Only when you send `utility`: the utility serves the state. |
| `home_type` | Only when you send `homeType`. `single_family` and `other` pass. `townhome` passes, and the customer must own the roof. `condo`, `multi_family` and `manufactured` are `not_evaluated`: PE reviews them. A manufactured home needs a 433A (or equivalent) certificate that shows a permanent foundation. A duplex or triplex needs the customer to own the roof and the electrical wall. |
| `ownership` | Only when you send `ownership`. The customer must own the home (fee simple). `renter` fails with `OWNERSHIP_NOT_ELIGIBLE`. |
| `existing_solar` | Only when you send `existingSolarOnProperty`. PE does not add to an existing solar system: `add_to_existing` fails with `EXISTING_SOLAR_NOT_ELIGIBLE`. A separate second system (`separate_system`) can qualify if it shares no inverter with the existing system. |
| `address` | The address is found, is in the United States and is in `stateCode`. If the address service does not answer, the check is `not_evaluated`. |

PE also has rules that the API cannot check, such as roof condition, roof type and HOA approval. PE checks them when it reviews the project.

`POST /tax-credits/domestic-content` checks a list of equipment against PE's AVL. Add `safeHarborOpportunityId` to include that opportunity's custom AVL. The response tells you if PV and storage meet the Domestic Content threshold. Use the answers in `pvDomesticContent` and `storageDomesticContent` of a pricing request. A SKU that PE cannot match is listed in `unresolved`. The call fails only when no SKU matches. PV needs a matched PV module and a matched inverter (one `pv_combo` item counts as both). Without them, `pv.percent` is `null` and `pv.reason` says what is missing. PE still computes storage. The `feoc` block also shows whether the equipment meets the FEOC (non-FEOC material assistance cost) threshold. The `feoc` result does not change `pv.eligible` or `storage.eligible`. The thresholds come from `year` (default: this year). A Safe Harbor beginning of construction date wins over it. The response `year` is the year that set the thresholds. FEOC rules start with construction in 2026. When `feoc.applies` is false, an included category is always eligible. Each item also has `feocPercent`.

`POST /tax-credits/energy-community` tells you if the site is in an Energy Community. You can also send `energyCommunity: "auto"` in a pricing request to run the same check.

`POST /sales-tax` reads the lease sales tax rate for a site. PE uses the same EREBOR rate resolver that pricing uses, and runs it on the address that Google returns. Add `netAmountDue` to get the tax amount. Always read `taxable`: in most states the lease is not taxable. `note` has text when PE could not fully confirm the rate. `jurisdiction.lowConfidence` is true when PE is not sure of the jurisdiction: the ZIP code has more than one rate and PE used the most common one, Google only partially matched the address (`resolvedAddress.partialMatch`), Google placed only the street and not the house number (`resolvedAddress.precision` is `street`), or the Colorado state lookup placed the address only approximately.

`POST /tax-credits/energy-community` and `POST /sales-tax` first find the site address with Google Maps. They run on the address Google returns and show it in `resolvedAddress`. Google must place a street address with a street number. When it finds only an approximate place, the response is `ADDRESS_NOT_FOUND`, and `details[0].closestMatch` has the place Google matched. One exception: outside Colorado, `POST /sales-tax` also accepts a match where Google places the street but not the house number. PE then reads the rate with the street line you sent and the city, state and ZIP code that Google found. `resolvedAddress.precision` is `street` and `jurisdiction.lowConfidence` is `true`. The Energy Community check and a Colorado sales tax check still need a street address that Google can place.

| `resolvedAddress` field | Type | Notes |
|---|---|---|
| `formatted` | string | The full address as Google Maps writes it. |
| `street` | string | The street number and the street name. When `precision` is `street`, the street line you sent. |
| `city` | string or null | The city. Null when Google returned no city. |
| `stateCode` | string | The 2-letter state code. |
| `zipCode` | string or null | The 5-digit ZIP code. Null when Google returned no ZIP code. |
| `county` | string or null | The county name, without the word County. |
| `latitude`, `longitude` | number | The point Google placed. |
| `precision` | `rooftop`, `interpolated`, `street` | `rooftop`: on the building. `interpolated`: between two known street numbers on the street. `street`: Google placed the street but not the house number. Only the sales tax check returns `street`, and only outside Colorado. |
| `partialMatch` | boolean | Google matched only part of the address you sent. Compare this address with your address before you use the result. |
| `mismatches` | array | Since 2.2. Each field where Google's address differs from the address you sent: `{field, sent, resolved}`, with `field` one of `zipCode`, `city`, `stateCode`. Empty when they agree. In `POST /sales-tax`, a mismatch sets `jurisdiction.lowConfidence`. |

## Lease pricing

Price a PE lease. The API runs the same calculation as the Lease Value Calculator in the Installer Portal and returns the same numbers. A quote never creates a project.

### How PE prices a lease

PE's product here is the prepaid lease (Synthetic Cash). The customer pays the Net Amount Due to the installer. PE pays the installer the PE payout, in two milestone payments. The steps below are the steps the API runs. Each step has the response field in brackets.

**1. The EPC.** `epcAmount` is the installer's price for the system before tax, in USD. Include any sales or use tax that the installer pays on equipment. Do not include the lease sales tax. PE adds that tax in step 8. The EPC must be from 1,000 to 500,000 US dollars. You can also send `systemSizeKw`, the DC size in kW (0.5 to 250); PE then checks that the EPC is from $1 to $10 per watt on a `solar_only` system, and at least $1 per watt on `solar_battery` (the EPC also pays for the battery); `battery_only` has no per watt check. `systemSizeKw` does not change the numbers. `contractDate` (default today) must be from one year before today to 90 days after today.

**2. Insurance.** The customer selects one of three insurance options:

| Option | What it means | Cost |
|---|---|---|
| 1 | The customer's homeowner's policy names PE as loss payee for the system. PE prefers this option. | None |
| 2 | The customer's homeowner's policy has no exclusion for solar or batteries. PE reviews the policy. | None |
| 3 | PE provides the coverage. The installer signs the Homeowners Insurance Rider. Use this option only when options 1 and 2 are not possible. | 2.5% of the EPC |

Option 3 does two things. It adds 2.5% of the EPC to the EPC basis before the lease math [`insuranceRiskAdjustment`]. It also takes 2.5% of the EPC from the Inspection Complete payment as a contribution to PE's risk pool [`insuranceRiderAmount`].

**3. Roofing.** Re-roofing is the only extra work that PE prices with the system. Split the roofing cost in two parts. Eligible roofing (`eligibleRoofingCost`) is the part under the solar array. It joins the EPC basis and gets the lease discount. Ineligible roofing (`ineligibleRoofingCost`) is the rest. It goes to the customer at full cost, with no discount. For example, a $40,000 re-roof where 25% of the area is under the array has $10,000 eligible and $30,000 ineligible roofing.

- Adjusted EPC = EPC + insurance adjustment + eligible roofing [`adjustedEpc`].
- Replacement cost of the system = EPC + insurance adjustment + all roofing [`replacementCost`].

**4. The lease factor.** The lease factor sets the customer's discount. The tier factor [`tierLeaseFactor`] depends on Domestic Content (`pvDomesticContent`, `storageDomesticContent`), Energy Community (`energyCommunity`) and the system type.

| Lease factor | Customer discount | When |
|---|---|---|
| 1.5384615 | 35% | Full Domestic Content: PV for `solar_only`, storage for `battery_only`, both PV and storage for `solar_battery`. |
| 1.4285714 | 30% | The baseline. All other cases. |
| 1.3333333 | 25% | No Domestic Content for the system type and no Energy Community. |

Energy Community alone does not raise the factor above the baseline. It prevents the 25% tier. PE confirms the Domestic Content and Energy Community bonuses at Permission to Operate, and the final factor depends on them.

**5. The Domestic Content bonus recipient.** At the 35% tier, `dcBonusRecipient` decides who gets the extra 5%. With `customer`, the customer gets the 35% discount. With `installer`, the customer gets the 30% baseline discount and PE pays the difference to the installer [`dcBonusAmount`]. At the other tiers the field has no effect. The factor that PE uses for the discount is [`leaseFactor`], and the discount it gives is [`leaseDiscountPercent`]. They show the baseline (1.4285714 and 30) when the installer keeps the bonus, and the tier values in all other cases.

**6. The discount and the Net Amount Due.**

- Lease discount = Adjusted EPC x (1 - 1 / `leaseFactor`) [`leaseDiscount`].
- Lease amount = replacement cost - lease discount [`leaseAmount`].
- Net Amount Due = lease amount - included incentives [`netAmountDue`]. This is what the customer pays, before lease sales tax.

Included incentives (`includedIncentive`):

- `hawaii_retitc`: the Hawaii Renewable Energy Technologies Income Tax Credit, 5% of the EPC. It is available only for Hawaii contracts dated before 2026-07-03, and the API does not accept those dates (`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`), so it prices no RETITC. It lowers the Net Amount Due and is part of the PE payout. Do not send an amount.
- `installer_managed`: a state incentive that the installer collects, for example from NYSERDA. It is available only in New York. Send the amount. It lowers the Net Amount Due. It is not part of the PE payout.

**7. The PE payout and Safe Harbor.**

- PE payout = lease discount + Domestic Content bonus + Hawaii RETITC [`pePayout`].
- Safe Harbor deduction = units x the opportunity's unit cost [`safeHarborDeduction`]. Send `safeHarbor` when the project uses PE Safe Harbor equipment. PE takes the deduction from the payout before the split, so the installer bears 2/3 of it at IC and 1/3 at PC.
- IC payment before deductions = (PE payout - Safe Harbor deduction) x 2/3 [`icPaymentGross`].
- PC payment = (PE payout - Safe Harbor deduction) x 1/3 [`pcPayment`].

**8. Lease sales tax.** PE finds the tax rate from the site address [`salesTax`]. PE collects lease sales tax only where PE's tax rules make the lease taxable. Today these states are Hawaii, Idaho, Texas, Utah, Maine and Colorado (local taxes only). Some other states tax a battery-only lease when the property has no solar; send `existingSolarOnProperty` for a `battery_only` system. The installer collects the tax from the customer on top of the Net Amount Due. PE deducts the tax from the IC payment. The tax is Net Amount Due x rate [`salesTax.amount`]. In Hawaii the rate includes the pass-on gross up. Always read `salesTax.taxable` and `salesTax.amount`; do not keep your own list of states. When `salesTax.needsAttention` has text, PE could not confirm the rate, and the quote also has a `SALES_TAX_NEEDS_ATTENTION` warning.

**9. The payments.**

- IC payment = IC payment before deductions - lease sales tax - insurance option 3 amount [`icPayment`]. PE pays it at Inspection Complete.
- PC payment [`pcPayment`]. PE pays it at Project Complete. It has no deductions.

The response also has `notes`: one plain sentence for each step that changed the numbers. You can show them to your users.

### Warnings

A quote has a `warnings` list. It is always present and is often empty. A warning does not change the numbers. Show it to your user.

| Code | Meaning |
|---|---|
| `STATE_NOT_ACTIVE_FOR_INSTALLER` | The address is in a state where PE operates, but the installer is not active there yet. The installer cannot submit a contract for this project until the state is active. The installer can request the state in the Installer Portal. |
| `SALES_TAX_NEEDS_ATTENTION` | PE could not fully confirm the lease sales tax for this address. The quote uses the rate PE found. PE confirms the tax when it reviews the project. |
| `ENERGY_COMMUNITY_NOT_CONFIRMED` | You sent `energyCommunity: true`, but PE's Energy Community lookup says the site address does not qualify. The quote is priced with `energyCommunity` false. Check the address, or send `"auto"`. |
| `ENERGY_COMMUNITY_NOT_VERIFIED` | You sent `energyCommunity: true` and PE could not run the Energy Community lookup right now. The quote uses `true`. PE confirms Energy Community in review. |
| `FIELD_NOT_APPLICABLE` | A flag does not apply to the system type and does not change the quote: `storageDomesticContent` on `solar_only`, `pvDomesticContent` on `battery_only`, or `existingSolarOnProperty` on a system with solar. `field` names it. |
| `ROOFING_COST_HIGH` | A roofing cost is more than the EPC. Check that it is in US dollars (not cents) and is the roofing cost only. The quote uses the amount as sent. `field` names it. |

A state where PE does not operate is an error (`STATE_NOT_SUPPORTED`). A PE state where the installer is not active yet still prices, with a `STATE_NOT_ACTIVE_FOR_INSTALLER` warning.

## Sungage pricing

Price a PE lease with a Sungage loan. The API runs the same calculation as the Sungage Loan Calculator in the Installer Portal.

These are the program requirements:

- The installer must be in the PE and Sungage program. PE enrolls the installer and stores the installer's Sungage account in Raceway. If not, the API returns `SUNGAGE_NOT_ENROLLED`.
- Send `X-PE-Actor-Email` on both Sungage endpoints. PE sends this email to Sungage as the user who requests the quote. The email must be a user of the installer in PE's records, and Sungage must know it as a user of the installer's Sungage account. If Sungage does not accept the email, the API returns `SUNGAGE_USER_NOT_REGISTERED`.
- The card is Sungage's Prepaid TPO card. Read the products, terms and rates for a state with `GET /pricing/sungage/products`. Then send one combination in `POST /pricing/sungage`.
- Terms longer than 25 years are not available. A `battery_only` system can have a term of 20 years or less.
- Included incentives are not priced with Sungage financing. Send `includedIncentive` as `none` or leave it out.
- In the Test environment, PE uses its own Sungage sandbox account. The actor email is still required and still checked against the installer.

The response has the PE lease block (`lease`, the same as `POST /pricing/lease`), the loan (`loan`), the installer payments (`installerPayments`) and the totals (`installerTotals`). If Sungage cannot quote a monthly payment, `loan.estimatedMonthlyPayment` is null and `loan.paymentsNote` explains it. The other amounts are still correct. When `pricingChecksPassed` is `false`, do not use the quote. Contact PE.

If Sungage does not answer, the API returns `SUNGAGE_UNAVAILABLE`. Retry the same request in a few minutes.

## Contract uploads

Create a PE project from a signed customer contract. In production, PE reads the contract and creates the project, or saves a draft for the installer. In the Test environment, PE simulates the result.

### The upload flow

1. **Create the upload.** Send `POST /contract-uploads` with `X-PE-Actor-Email`. Send your own id for the project in `vendorProjectId`. The response has `uploadId` and a signed `uploadUrl`. The URL is valid for 15 minutes.
2. **Put the file.** Send the PDF bytes with HTTP `PUT` to `uploadUrl`. **Send every header in `uploadHeaders`, with the exact values.** Today these are `Content-Type`, `x-goog-if-generation-match` and `x-goog-content-length-range`. Since 2.2, `x-goog-content-length-range` is `sizeBytes,sizeBytes`: the file must be exactly the `sizeBytes` you declared. If a header is missing or different, the storage service refuses the file. Do not send an Authorization header. The file limit is 25 MB. The URL accepts one file only: a second `PUT` gets HTTP 412.
3. **Submit.** Send `POST /contract-uploads/{uploadId}/submit`. PE checks that the file exists, is 25 MB or less and starts with `%PDF-`. The response is HTTP 202 with status `queued`.
4. **Poll.** Read `GET /contract-uploads/{uploadId}` until `status` is `completed` or `failed`. Wait 5 seconds before the first read. Then double the wait after each read, up to 60 seconds. In production, the review usually takes a few minutes.
5. **Act on the outcome.** Read `outcome`, `outcomeMessage` and `nextStep`. Show `outcomeMessage` and `nextStep` to your user. When a project exists, `project.projectId` is the PE Project ID. Then follow the project with `GET /projects/{projectId}` and webhooks.

Rules:

- A `vendorProjectId` works for one upload, for each installer and environment. To upload again for the same project, send a new `vendorProjectId`, for example with a suffix such as `-2`. A repeat returns `DUPLICATE_VENDOR_PROJECT_ID`, and `details` give the earlier `uploadId`.
- One exception: when the upload URL of an upload expires before the upload is submitted, you can create a new upload with the same `vendorProjectId`. The old upload then has status `expired`.
- PE checks the installer before it creates the upload: the connected organization is an installer, it is not on hold, it is active in `stateCode` and it has the PE lease enabled.
- `productType` is `Synthetic Cash`. Other products are not supported in v2.
- If submit fails with a 5xx error, send submit again. A repeat after a successful submit returns `UPLOAD_ALREADY_SUBMITTED`.
- A draft is not a project. The installer can finish a draft in the Installer Portal. When the installer creates the project from the draft, the upload shows the project, and you can read it.

### Upload status

| Status | Meaning |
|---|---|
| `awaiting_file` | The upload exists. PE waits for the file and the submit call. |
| `queued` | PE has the file. The review has not started. |
| `processing` | PE is reading the contract. |
| `completed` | PE has a result. Read `outcome`. |
| `failed` | PE could not finish. Read `outcome`. |
| `expired` | The upload URL expired before a file arrived, and a newer upload took the `vendorProjectId`. The upload has no `outcome`. The upload URL expired before a file arrived, so this upload was closed and its vendorProjectId was released. Use the newer upload for this vendorProjectId, or create a new upload with POST /v2/design/contract-uploads. |

### Outcomes

| Outcome | Status | What it means | Next step |
|---|---|---|---|
| `project_created` | `completed` | Participate Energy read the contract and created the project. | Read the project with GET /v2/design/projects/{projectId} and follow its Actions and IC and PC approval status. |
| `draft_failed_basic_tests` | `completed` | The contract was read, but it did not pass the basic checks, so Participate Energy saved it as a draft instead of a project. The failed checks are listed in checks. | The installer opens the draft in the Installer Portal, fixes the listed problems and creates the project there, or uploads a corrected contract with a new vendorProjectId. |
| `draft_invalid_document` | `completed` | The file does not look like a Participate Energy customer agreement, so no project was created. | Check that the right document was uploaded, then upload the signed Participate Energy customer agreement with a new vendorProjectId. |
| `draft_duplicate` | `completed` | This contract matches a project that already exists for this installer, so it was saved as a draft and no new project was created. | The installer reviews the draft in the Installer Portal. If it is a new project, the installer can create it there. |
| `draft_manual_entry` | `completed` | The contract could not be read automatically, so it was saved as a draft for the installer to complete. | The installer opens the draft in the Installer Portal and enters the missing details to create the project. |
| `sibyl_error` | `failed` | Participate Energy could not finish reading the contract because of a processing error. No project was created. | Ask the installer to retry the upload in the Installer Portal, or create a new upload with a new vendorProjectId. |
| `canon_rejected` | `completed` | The contract was read, but its data did not pass Participate Energy's project checks, so no project was created. | The installer reviews the upload in the Installer Portal. Contact raceway.support@participate.energy with the uploadId if the contract is correct. |
| `product_mismatch` | `completed` | The contract is for a different Participate Energy product than the one on the upload, so no project was created. | Ask the installer to retry the upload in the Installer Portal, or create a new upload with a new vendorProjectId. |
| `cancelled` | `completed` | The upload was cancelled before a project was created. | Create a new upload if the contract should still become a project. |

`checks` lists the failed checks and the warnings of the review, in the words the installer sees in the Installer Portal.

### Test environment scenarios

In the Test environment, send `sandboxScenario` to choose the result. The default is `project_created`. Do not send `sandboxScenario` with a production token (`SANDBOX_FIELD_IN_LIVE`).

| `sandboxScenario` | Outcome | Result |
|---|---|---|
| `project_created` | `project_created` | PE creates a Test project. Status `Active`, milestone `Project Onboarded`, review `Under Review (PE)`. |
| `project_created_action_required` | `project_created` | PE creates a Test project with the review at `Action Required (Installer)` and two sample Actions. |
| `draft_failed_basic_tests` | `draft_failed_basic_tests` | No project. The upload has sample failed checks (a missing signature and an EPC mismatch). |
| `draft_invalid_document` | `draft_invalid_document` | No project. The file does not read as a PE customer agreement. |
| `draft_duplicate` | `draft_duplicate` | No project. The contract matches an existing project. |
| `product_mismatch` | `product_mismatch` | No project. The contract is for a different PE product. |
| `canon_rejected` | `canon_rejected` | No project. The contract data did not pass PE's project checks. |
| `sibyl_error` | `sibyl_error` | No project. The status is `failed`. |

The Test status follows the clock: `queued` for the first 5 seconds after submit, `processing` until 20 seconds, then `completed` (or `failed` for `sibyl_error`). A Test project has the customer name "Sandbox Customer" and a placeholder address. Its PE Project ID starts with `SBX-`, so it can never match a production id.

## Projects

Read the status of a project that you created. You can read only the projects that your company created for this installer, in the environment of your token. Every other id returns `RESOURCE_NOT_FOUND`.

Find a project by the PE Project ID (`GET /projects/{projectId}`) or by your own id (`GET /projects/by-vendor-id/{vendorProjectId}`).

The response has status fields only. It has no customer name, no address and no financial data.

| Field | Meaning |
|---|---|
| `status` | The project status, for example `Active`, `At-risk`, `On Hold`, `Cancelled` or `Completed`. |
| `milestone` | The current milestone, for example `Project Onboarded`, `Inspection Complete` or `Project Complete`. |
| `documentReviewStatus` | `Action Required (Installer)`, `Under Review (PE)` or `Approved`. |
| `actionsRequired` | The open Actions that the installer sees in the Installer Portal. An Action is a task for the installer, for example a missing document or a correction. |
| `icApproval` | The status and date of the Inspection Complete (IC) approval. |
| `pcApproval` | The status and date of the Project Complete (PC) approval. |

PE sets `icApproval.status` with these rules, in this order:

1. `approved`: PE approved IC. `date` is the approval date. A cancelled project keeps its dates.
2. `action_required`: the milestone is `Inspection Complete` and `documentReviewStatus` is `Action Required (Installer)`. The installer must act on `actionsRequired`.
3. `under_review`: the milestone is `Inspection Complete` and PE reviews the documents.
4. `not_started`: all other cases, for example `Project Onboarded`.

`pcApproval.status` uses the same rules with the PC approval date and the `Project Complete` milestone.

Use webhooks for IC and PC approval. Read the project when you need the other fields. Do not poll a project more than once each hour.

## Webhooks

Get a call from PE when PE approves IC or PC on a project that you created.

### Set up

- Set one URL for each environment with `PUT /webhooks`. The URL must use `https` on port 443, with a host name that resolves to public addresses only. The response gives the signing secret. Store it. `GET /webhooks` does not return it.
- Send a test event with `POST /webhooks/test`. It sends one `ping` event and returns the result.
- Get a new secret with `POST /webhooks/rotate-secret`. The old secret stops working at once.
- The URL is for your company. You get events for every installer where you hold an active grant with the `webhooks:manage` scope. Use `data.grantId` to find the installer.

### Events

| Type | When |
|---|---|
| `project.ic_approved` | PE approved the Inspection Complete milestone. `data.icApproval` has the date. |
| `project.pc_approved` | PE approved the Project Complete milestone. `data.pcApproval` has the date. |
| `ping` | You called `POST /webhooks/test`. `data` is empty. |

PE sends a `POST` with a JSON body and these headers:

| Header | Value |
|---|---|
| `PE-Webhook-Id` | The event id (`evt_...`). It is the same on every retry. |
| `PE-Webhook-Timestamp` | The send time in Unix seconds. |
| `PE-Signature` | `t=<timestamp>,v1=<signature>` |
| `User-Agent` | `ParticipateEnergy-Webhooks/2` |

Answer with any 2xx status within 10 seconds. PE does not follow redirects. Any other answer is a failure. After a failure, PE tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours. Then PE stops. Each event type comes at most once for each project, but a retry can arrive after a success that timed out, so use `PE-Webhook-Id` to ignore repeats. PE sends an event only while you hold an active grant with `webhooks:manage` for the installer. Without one, PE counts the attempt as a failure and tries again on the same schedule. If the installer connects you again before the last try, you get the event.

### Verify the signature

The signature is the hex HMAC-SHA256 of `<timestamp>.<raw body>`. The key is your full signing secret, including the `whsec_` prefix. Do these steps for each event:

1. Read the raw request body as bytes. Do not parse and serialize the JSON again before you verify it.
2. Read `t` and `v1` from the `PE-Signature` header.
3. Reject the event if `t` is more than 300 seconds from your clock. This is the replay window.
4. Compute the HMAC and compare it with `v1` in constant time.
5. Ignore the event if you already processed its `PE-Webhook-Id`. Keep the ids for at least 3 days.

Node.js:

```js
const crypto = require("crypto");

// Returns true when the PE-Signature header is valid and fresh.
function verifyPeSignature(secret, header, rawBody, toleranceSeconds = 300) {
  const parts = {};
  for (const item of String(header || "").split(",")) {
    const i = item.indexOf("=");
    if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim();
  }
  const t = Number(parts.t);
  if (!Number.isInteger(t)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.`, "utf8").update(rawBody).digest("hex");
  const received = String(parts.v1 || "");
  if (received.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

// Express: read the body as raw bytes on this route.
// app.post("/pe/webhooks", express.raw({type: "application/json"}), (req, res) => {
//   if (!verifyPeSignature(process.env.PE_WEBHOOK_SECRET, req.get("PE-Signature"), req.body)) {
//     return res.status(400).end();
//   }
//   const event = JSON.parse(req.body.toString("utf8"));
//   res.status(200).end();
// });
```

Python:

```python
import hashlib
import hmac
import time


def verify_pe_signature(secret: str, header: str, raw_body: bytes, tolerance_seconds: int = 300) -> bool:
    """Returns True when the PE-Signature header is valid and fresh."""
    parts = {}
    for item in (header or "").split(","):
        key, sep, value = item.partition("=")
        if sep:
            parts[key.strip()] = value.strip()
    try:
        t = int(parts.get("t", ""))
    except ValueError:
        return False
    if abs(int(time.time()) - t) > tolerance_seconds:
        return False
    signed = f"{t}.".encode("utf-8") + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))
```

## Sandbox

Move a Test project through its life to test your status screens and your webhook receiver. These endpoints work only with Test tokens. A production token gets `SANDBOX_ONLY`.

| Event | What changes |
|---|---|
| `action_required` | The open review (IC, or PC after IC approval) moves to `Action Required (Installer)` with one new sample Action. The milestone moves to that review's milestone. |
| `under_review` | The open review moves to `Under Review (PE)`. Open Actions close. |
| `ic_approved` | The IC approval date is today. The milestone is `Inspection Complete` and the review is `Approved`. Open Actions close. PE sends `project.ic_approved`. |
| `pc_approved` | Needs IC approval first. The PC approval date is today. The milestone is `Project Complete` and the review is `Approved`. PE sends `project.pc_approved`. |
| `cancelled` | The status is `Cancelled`. The dates stay. |

A cancelled project takes no other events. A PC-approved project takes no review events. These return `SANDBOX_TRANSITION_INVALID`. A repeat of an approval or a cancel changes nothing and returns HTTP 200, so a retry is safe. PE tries the webhook once during the call, and retries it on the normal schedule.

## Errors

Every error has the same shape:

```json
{
  "error": {
    "code": "STATE_NOT_ACTIVE_FOR_INSTALLER",
    "message": "The installer is not active in NV. Use a state from GET /v2/design/states, or ask the installer to request the state in the Installer Portal.",
    "retryable": false,
    "details": [
      {
        "field": "stateCode",
        "issue": "The installer is not active in this state."
      }
    ],
    "docsUrl": "https://api.participate.energy/docs/design/v2/#error-STATE_NOT_ACTIVE_FOR_INSTALLER"
  },
  "meta": {
    "requestId": "req_9Bv4Nc7Xz2Lk5Hj8Gf3D",
    "environment": "live",
    "timestamp": "2026-11-10T18:02:11.482Z"
  }
}
```

- `code` is one of the codes below. Your code should act on `code`. The `message` text can change.
- `message` is a full sentence. It says what happened and what to do. You can show it to your users.
- `retryable` tells you if the same request can succeed later.
- `details` lists the fields with problems. It is empty when no field applies.
- `docsUrl` links to the code in this section.

### Retry rules

1. When `retryable` is `false`, change the request or the data first. The same request returns the same error.
2. On HTTP 429, wait the seconds in the `Retry-After` header. Then send the same request.
3. On HTTP 500, 503 and 504, wait 1 second, then 2, 4, 8 and 16 seconds. Stop after 5 tries and contact PE with the request id.
4. GET calls, `POST /oauth/token`, the eligibility and tax credit checks and the pricing calls are safe to repeat.
5. `POST /contract-uploads` is not safe to repeat. If you lost its response, a repeat with the same `vendorProjectId` returns `DUPLICATE_VENDOR_PROJECT_ID` with the `uploadId`. You cannot get a new upload URL for that upload. Create a new upload with a new `vendorProjectId`, or wait until the first upload URL expires (15 minutes) and use the same `vendorProjectId` again.
6. `POST /contract-uploads/{uploadId}/submit` is safe to repeat after a 5xx error.

### Common errors

Every endpoint that takes an access token can return these codes: [`AUTH_HEADER_MISSING`](#error-AUTH_HEADER_MISSING), [`AUTH_HEADER_MALFORMED`](#error-AUTH_HEADER_MALFORMED), [`TOKEN_INVALID`](#error-TOKEN_INVALID), [`TOKEN_EXPIRED`](#error-TOKEN_EXPIRED), [`CLIENT_REVOKED`](#error-CLIENT_REVOKED), [`CLIENT_EXPIRED`](#error-CLIENT_EXPIRED), [`VENDOR_SUSPENDED`](#error-VENDOR_SUSPENDED), [`ENVIRONMENT_NOT_ENABLED`](#error-ENVIRONMENT_NOT_ENABLED), [`GRANT_NOT_FOUND`](#error-GRANT_NOT_FOUND), [`GRANT_REVOKED`](#error-GRANT_REVOKED), [`INTEGRATION_NOT_ENABLED`](#error-INTEGRATION_NOT_ENABLED), [`ACTOR_INVALID_EMAIL`](#error-ACTOR_INVALID_EMAIL), [`ACTOR_NOT_ON_ROSTER`](#error-ACTOR_NOT_ON_ROSTER), [`BODY_TOO_LARGE`](#error-BODY_TOO_LARGE), [`RATE_LIMITED`](#error-RATE_LIMITED), [`SERVICE_DISABLED`](#error-SERVICE_DISABLED), [`INTERNAL_ERROR`](#error-INTERNAL_ERROR). Endpoints with a scope can also return [`SCOPE_NOT_GRANTED`](#error-SCOPE_NOT_GRANTED). Endpoints with a JSON body or query parameters can also return [`UNSUPPORTED_MEDIA_TYPE`](#error-UNSUPPORTED_MEDIA_TYPE), [`INVALID_JSON`](#error-INVALID_JSON), [`VALIDATION_FAILED`](#error-VALIDATION_FAILED), [`UNKNOWN_FIELD`](#error-UNKNOWN_FIELD). A path that does not exist returns [`ROUTE_NOT_FOUND`](#error-ROUTE_NOT_FOUND), and a wrong method returns [`METHOD_NOT_ALLOWED`](#error-METHOD_NOT_ALLOWED). Each endpoint lists its other codes.


### HTTP 400: the request is not valid

<a id="error-INVALID_JSON"></a>

#### INVALID_JSON

HTTP 400. Retry the same request: no.

> The request body is not valid JSON. Send a JSON object with Content-Type: application/json.

Note: Participate Energy's hosting platform reads a body sent with Content-Type: application/json before the API does. If that body is not valid JSON, the platform refuses it with HTTP 400 and a plain "Bad Request" page, without the JSON error body or the X-Request-Id header. Treat an HTTP 400 that has no JSON error body as INVALID_JSON and check the JSON you send. The same happens for a body that is the JSON value `null`. The platform parses the JSON before the API code runs, so the API cannot answer these two cases with its own error body.

<a id="error-VALIDATION_FAILED"></a>

#### VALIDATION_FAILED

HTTP 400. Retry the same request: no.

> The request did not pass validation ({count} problem(s)). Fix the fields listed in details and send the request again.

Each entry in `details` has `field` (a dotted path such as `address.zipCode`), `issue`, and when known `expected` and `received`. `received` is the type of the value you sent, or the value itself for numbers, booleans and enum values.

<a id="error-UNKNOWN_FIELD"></a>

#### UNKNOWN_FIELD

HTTP 400. Retry the same request: no.

> The request has {count} field(s) this endpoint does not accept. Remove the fields listed in details and send the request again.

Each entry in `details` names one unknown field in `field`.

<a id="error-CONNECTION_CODE_INVALID"></a>

#### CONNECTION_CODE_INVALID

HTTP 400. Retry the same request: no.

> The connection code is not recognized. Check that the full code (it starts with pec_) was copied without spaces, or ask the installer for a new one.

<a id="error-ACTOR_REQUIRED"></a>

#### ACTOR_REQUIRED

HTTP 400. Retry the same request: no.

> This endpoint needs the sales rep's email in the X-PE-Actor-Email header. Send the email of the installer's user who is doing the work.

<a id="error-ACTOR_INVALID_EMAIL"></a>

#### ACTOR_INVALID_EMAIL

HTTP 400. Retry the same request: no.

> The actor email is not a valid email address. Send one email address, for example rep@installer.com.

<a id="error-SANDBOX_SCENARIO_INVALID"></a>

#### SANDBOX_SCENARIO_INVALID

HTTP 400. Retry the same request: no.

> The sandboxScenario {received} is not one of: {allowed}. Send one of the listed scenarios, or leave it out for project_created.

<a id="error-SANDBOX_FIELD_IN_LIVE"></a>

#### SANDBOX_FIELD_IN_LIVE

HTTP 400. Retry the same request: no.

> The field {field} works only in the Test environment. Remove it from live requests.

<a id="error-WEBHOOK_URL_INVALID"></a>

#### WEBHOOK_URL_INVALID

HTTP 400. Retry the same request: no.

> The webhook URL is not usable: {reason}. Send an absolute https URL with a public host name, no user name or password, at most 2048 characters.

<a id="error-WEBHOOK_URL_NOT_HTTPS"></a>

#### WEBHOOK_URL_NOT_HTTPS

HTTP 400. Retry the same request: no.

> The webhook URL must use https on port 443. Send an https URL without a custom port.

### HTTP 401: authentication

<a id="error-AUTH_HEADER_MISSING"></a>

#### AUTH_HEADER_MISSING

HTTP 401. Retry the same request: no.

> The request has no Authorization header. Send "Authorization: Bearer <accessToken>" with a token from POST /v2/design/oauth/token.

<a id="error-AUTH_HEADER_MALFORMED"></a>

#### AUTH_HEADER_MALFORMED

HTTP 401. Retry the same request: no.

> The Authorization header is not in the form "Bearer <accessToken>". Send the access token from POST /v2/design/oauth/token after the word Bearer and one space.

<a id="error-TOKEN_INVALID"></a>

#### TOKEN_INVALID

HTTP 401. Retry the same request: no.

> The access token is not valid: it was not issued by the Participate Energy Design API or it was changed. Get a new token from POST /v2/design/oauth/token.

<a id="error-TOKEN_EXPIRED"></a>

#### TOKEN_EXPIRED

HTTP 401. Retry the same request: no.

> The access token expired at {expiredAt}. Tokens last 60 minutes; get a new token from POST /v2/design/oauth/token and send the request again.

<a id="error-INVALID_CLIENT"></a>

#### INVALID_CLIENT

HTTP 401. Retry the same request: no.

> The client credentials are not recognized. Send the clientId and clientSecret Participate Energy issued to you, in the request body or as HTTP Basic authentication.

<a id="error-CLIENT_REVOKED"></a>

#### CLIENT_REVOKED

HTTP 401. Retry the same request: no.

> The client credential {clientId} has been revoked. Use an active credential, or ask Participate Energy for a new one.

<a id="error-CLIENT_EXPIRED"></a>

#### CLIENT_EXPIRED

HTTP 401. Retry the same request: no.

> The client credential {clientId} expired at {expiredAt}. Ask Participate Energy for a replacement credential.

### HTTP 403: access

<a id="error-VENDOR_SUSPENDED"></a>

#### VENDOR_SUSPENDED

HTTP 403. Retry the same request: no.

> Design API access for your company is suspended. Contact Participate Energy at raceway.support@participate.energy.

<a id="error-ENVIRONMENT_NOT_ENABLED"></a>

#### ENVIRONMENT_NOT_ENABLED

HTTP 403. Retry the same request: no.

> The {environment} environment is not enabled for your company. Use a credential for an enabled environment, or ask Participate Energy to enable it.

<a id="error-GRANT_REVOKED"></a>

#### GRANT_REVOKED

HTTP 403. Retry the same request: no.

> The connection {grantId} to this installer was revoked. Ask the installer to create a new connection code in the Installer Portal and exchange it with POST /v2/design/connections/exchange.

<a id="error-INTEGRATION_NOT_ENABLED"></a>

#### INTEGRATION_NOT_ENABLED

HTTP 403. Retry the same request: no.

> This installer does not have your integration enabled. Ask the installer to contact Participate Energy to enable it.

<a id="error-SCOPE_NOT_GRANTED"></a>

#### SCOPE_NOT_GRANTED

HTTP 403. Retry the same request: no.

> This endpoint needs the scope {scope}, and your token does not carry it. The token carries the scopes both your credential and the installer's connection allow; ask the installer for a connection with this scope, or ask Participate Energy to add it to your credential.

Read your scopes with `GET /ping`.

<a id="error-ACTOR_NOT_ON_ROSTER"></a>

#### ACTOR_NOT_ON_ROSTER

HTTP 403. Retry the same request: no.

> The actor email is not an active user of this installer and its domain is not one of the installer's allowed domains. Send the email of the installer's sales rep as Raceway knows it, or ask the installer to add the user.

<a id="error-INSTALLER_NOT_ELIGIBLE"></a>

#### INSTALLER_NOT_ELIGIBLE

HTTP 403. Retry the same request: no.

> The connected organization is not an installer, so it cannot create projects. Contract uploads work only for installer organizations; ask the installer to create the connection code from its own Installer Portal account.

<a id="error-INSTALLER_ON_HOLD"></a>

#### INSTALLER_ON_HOLD

HTTP 403. Retry the same request: no.

> This installer cannot create new projects right now because its account is on hold. Ask the installer to contact Participate Energy.

<a id="error-STATE_NOT_ACTIVE_FOR_INSTALLER"></a>

#### STATE_NOT_ACTIVE_FOR_INSTALLER

HTTP 403. Retry the same request: no.

> The installer is not active in {stateCode}. Use a state from GET /v2/design/states, or ask the installer to request the state in the Installer Portal.

`POST /eligibility` reports it as a failed check. Pricing reports it as a warning. Contract uploads return it as an error.

<a id="error-PRODUCT_NOT_ENABLED"></a>

#### PRODUCT_NOT_ENABLED

HTTP 403. Retry the same request: no.

> The product {productType} is not enabled for this installer. Ask the installer to contact Participate Energy.

`POST /eligibility` reports it as a failed check. Contract uploads return it as an error.

<a id="error-SUNGAGE_NOT_ENROLLED"></a>

#### SUNGAGE_NOT_ENROLLED

HTTP 403. Retry the same request: no.

> This installer is not enrolled in the Participate Energy and Sungage program, or its Sungage account is not set up in Raceway. Ask the installer to contact Participate Energy to enroll.

<a id="error-SUNGAGE_USER_NOT_REGISTERED"></a>

#### SUNGAGE_USER_NOT_REGISTERED

HTTP 403. Retry the same request: no.

> Sungage did not accept the actor email as a user of this installer's Sungage account. Send the email of a user registered with Sungage, or ask the installer to register the user with Sungage.

<a id="error-SANDBOX_ONLY"></a>

#### SANDBOX_ONLY

HTTP 403. Retry the same request: no.

> This endpoint works only with Test environment tokens. Get a token with your Test credential to simulate project events.

### HTTP 404: not found

<a id="error-ROUTE_NOT_FOUND"></a>

#### ROUTE_NOT_FOUND

HTTP 404. Retry the same request: no.

> No Design API route matches {received}. Check the path against the API reference at https://api.participate.energy/docs/design/v2/.

<a id="error-RESOURCE_NOT_FOUND"></a>

#### RESOURCE_NOT_FOUND

HTTP 404. Retry the same request: no.

> No {resource} with this id is available to your integration for this installer in the {environment} environment. Check the id, the installer connection and the environment of your token.

PE returns this code for an id that does not exist, for an id of another vendor or installer, and for an id from the other environment.

<a id="error-GRANT_NOT_FOUND"></a>

#### GRANT_NOT_FOUND

HTTP 404. Retry the same request: no.

> The grant id {grantId} does not name a connection for your company. Use the grantId returned by POST /v2/design/connections/exchange.

<a id="error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"></a>

#### SAFE_HARBOR_OPPORTUNITY_NOT_FOUND

HTTP 404. Retry the same request: no.

> The Safe Harbor opportunity {opportunityId} is not available to this installer. Use an opportunityId from GET /v2/design/safe-harbor/opportunities.

### HTTP 405: method not allowed

<a id="error-METHOD_NOT_ALLOWED"></a>

#### METHOD_NOT_ALLOWED

HTTP 405. Retry the same request: no.

> The method {method} is not allowed on {path}. Allowed methods: {allowed}.

The `Allow` header lists the allowed methods.

### HTTP 409: conflict

<a id="error-CONNECTION_CODE_USED"></a>

#### CONNECTION_CODE_USED

HTTP 409. Retry the same request: no.

> This connection code was already exchanged. A code works once; ask the installer to create a new one in the Installer Portal.

<a id="error-DUPLICATE_VENDOR_PROJECT_ID"></a>

#### DUPLICATE_VENDOR_PROJECT_ID

HTTP 409. Retry the same request: no.

> The vendorProjectId {vendorProjectId} was already used for this installer in the {environment} environment. Read that upload with the uploadId in details, or send a different vendorProjectId.

`details` give the earlier `uploadId`, and `projectId` when that upload created a project. A `vendorProjectId` works for one upload only.

<a id="error-UPLOAD_ALREADY_SUBMITTED"></a>

#### UPLOAD_ALREADY_SUBMITTED

HTTP 409. Retry the same request: no.

> Upload {uploadId} was already submitted and is now {status}. Poll GET /v2/design/contract-uploads/{uploadId} for the result instead of submitting again.

`details` give the current `status`.

<a id="error-SANDBOX_TRANSITION_INVALID"></a>

#### SANDBOX_TRANSITION_INVALID

HTTP 409. Retry the same request: no.

> The event {event} cannot be simulated on this project now: {reason}. Send an event that fits the project's current state.

### HTTP 410: gone

<a id="error-CONNECTION_CODE_EXPIRED"></a>

#### CONNECTION_CODE_EXPIRED

HTTP 410. Retry the same request: no.

> This connection code expired. Codes last 72 hours; ask the installer to create a new one in the Installer Portal.

<a id="error-CONNECTION_CODE_REVOKED"></a>

#### CONNECTION_CODE_REVOKED

HTTP 410. Retry the same request: no.

> The installer revoked this connection code. Ask the installer to create a new one in the Installer Portal.

<a id="error-UPLOAD_URL_EXPIRED"></a>

#### UPLOAD_URL_EXPIRED

HTTP 410. Retry the same request: no.

> The upload URL for upload {uploadId} expired before a file arrived. Create a new upload with POST /v2/design/contract-uploads; you can use the same vendorProjectId.

<a id="error-UTILITY_LIST_BY_STATE_RETIRED"></a>

#### UTILITY_LIST_BY_STATE_RETIRED

HTTP 410. Retry the same request: no.

> Utilities are listed by ZIP code. Use GET /v2/design/utilities?zipCode={zipCode}.

`GET /utilities/{stateCode}` returns it. Call `GET /utilities?zipCode=` instead.

### HTTP 413: too large

<a id="error-BODY_TOO_LARGE"></a>

#### BODY_TOO_LARGE

HTTP 413. Retry the same request: no.

> The request body is {received} bytes, more than the {max} bytes allowed. Send a smaller JSON body.

<a id="error-UPLOAD_FILE_TOO_LARGE"></a>

#### UPLOAD_FILE_TOO_LARGE

HTTP 413. Retry the same request: no.

> The uploaded file is {received} bytes, more than the {max} bytes allowed. Create a new upload for a smaller PDF; you can use the same vendorProjectId.

The upload URL accepts one file only. Create a new upload with a new `vendorProjectId`, or wait until the first upload URL expires (15 minutes) and use the same `vendorProjectId` again.

### HTTP 415: media type

<a id="error-UNSUPPORTED_MEDIA_TYPE"></a>

#### UNSUPPORTED_MEDIA_TYPE

HTTP 415. Retry the same request: no.

> The request Content-Type is {received}, but this endpoint accepts {expected}. Send the body with that Content-Type.

### HTTP 422: the request breaks a rule

<a id="error-CONNECTION_CODE_WRONG_VENDOR"></a>

#### CONNECTION_CODE_WRONG_VENDOR

HTTP 422. Retry the same request: no.

> This connection code was created for a different vendor. Ask the installer to create a code for your company in the Installer Portal.

<a id="error-NO_SCOPES_AVAILABLE"></a>

#### NO_SCOPES_AVAILABLE

HTTP 422. Retry the same request: no.

> None of the scopes on this connection code are on any active credential of your company, so the connection would allow nothing. Ask Participate Energy to add the scopes, or ask the installer for a code with scopes you hold.

<a id="error-ADDRESS_NOT_FOUND"></a>

#### ADDRESS_NOT_FOUND

HTTP 422. Retry the same request: no.

> PE could not find this street address. Check the street number, street name, city and zipCode, and send the request again.

`POST /sales-tax` and `POST /tax-credits/energy-community` find the address with Google Maps and need a street number and a street name. Outside Colorado, `POST /sales-tax` also accepts a street that Google places without the house number. When Google finds only an approximate place, `details[0].closestMatch` has the place it matched.

<a id="error-ADDRESS_AMBIGUOUS"></a>

#### ADDRESS_AMBIGUOUS

HTTP 422. Retry the same request: no.

> The address matches more than one place. Add the house number, unit or ZIP code so it matches one place.

PE reserves this code. The API does not return it today.

<a id="error-ADDRESS_OUTSIDE_US"></a>

#### ADDRESS_OUTSIDE_US

HTTP 422. Retry the same request: no.

> The address is not in the United States. Participate Energy works with US addresses only.

<a id="error-ADDRESS_PO_BOX"></a>

#### ADDRESS_PO_BOX

HTTP 422. Retry the same request: no.

> A site address cannot be a PO Box. Send the street address where the system is installed.

Every endpoint that takes a site address returns it: `POST /eligibility`, `POST /tax-credits/energy-community`, `POST /sales-tax`, `POST /pricing/lease` and `POST /pricing/sungage`. PO Box, P.O. Box, Post Office Box, POB, P.O.B. and PMB are refused in any case. A mailing address is not a site address.

<a id="error-STATE_NOT_SUPPORTED"></a>

#### STATE_NOT_SUPPORTED

HTTP 422. Retry the same request: no.

> Participate Energy does not operate in {stateCode}. Use a state from GET /v2/design/states.

`POST /eligibility` reports it as a failed check. Pricing and contract uploads return it as an error.

<a id="error-STATE_MISMATCH"></a>

#### STATE_MISMATCH

HTTP 422. Retry the same request: no.

> The site address or its ZIP code is in {addressState}, but the request says {stateCode}. Send the stateCode and zipCode of the site address.

<a id="error-UTILITY_NOT_FOUND"></a>

#### UTILITY_NOT_FOUND

HTTP 422. Retry the same request: no.

> The utility is not on the list for {stateCode}. Use a name from GET /v2/design/utilities, sending the zipCode of the site address.

`POST /eligibility` reports it as a failed check.

<a id="error-HOME_TYPE_NOT_ELIGIBLE"></a>

#### HOME_TYPE_NOT_ELIGIBLE

HTTP 422. Retry the same request: no.

> Participate Energy does not lease systems on {homeType} homes. The customer does not qualify for a Participate Energy lease.

PE reserves this code. The API does not return it today.

<a id="error-OWNERSHIP_NOT_ELIGIBLE"></a>

#### OWNERSHIP_NOT_ELIGIBLE

HTTP 422. Retry the same request: no.

> The customer must own the home (fee simple ownership). A renter does not qualify for a Participate Energy lease.

`POST /eligibility` reports it as a failed check.

<a id="error-EXISTING_SOLAR_NOT_ELIGIBLE"></a>

#### EXISTING_SOLAR_NOT_ELIGIBLE

HTTP 422. Retry the same request: no.

> Participate Energy does not add to an existing solar system. A separate second system can qualify; send existingSolarOnProperty "separate_system" if that is the case.

`POST /eligibility` reports it as a failed check.

<a id="error-EQUIPMENT_NOT_ON_AVL"></a>

#### EQUIPMENT_NOT_ON_AVL

HTTP 422. Retry the same request: no.

> The equipment {sku} is not on the Participate Energy approved vendor list. Use a SKU from GET /v2/design/avl.

`POST /tax-credits/domestic-content` returns this code as an error only when no item matches. Otherwise each item that does not match is in `unresolved`.

<a id="error-EQUIPMENT_AMBIGUOUS"></a>

#### EQUIPMENT_AMBIGUOUS

HTTP 422. Retry the same request: no.

> The equipment {sku} matches more than one item on the approved vendor list. Send the exact SKU from GET /v2/design/avl.

`POST /tax-credits/domestic-content` returns this code as an error only when no item matches. Otherwise each item that does not match is in `unresolved`.

<a id="error-EQUIPMENT_CATEGORY_MISMATCH"></a>

#### EQUIPMENT_CATEGORY_MISMATCH

HTTP 422. Retry the same request: no.

> SKU {sku} is on the AVL as {avlCategory}; send category {avlCategory}.

`POST /tax-credits/domestic-content`: the SKU is on the AVL, but under another category. `details[].didYouMean` has the AVL category. Any such line refuses the request.

<a id="error-EQUIPMENT_QUANTITY_OUT_OF_RANGE"></a>

#### EQUIPMENT_QUANTITY_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

> The {field} {received} is more than {max}, the most Participate Energy accepts on one {category} line. Send the number of units, for example the module count, not the system size in watts.

`POST /tax-credits/domestic-content`: a `pv_module` or `pv_combo` line has at most 500 units. 7200 modules is usually the system size in watts.

<a id="error-SAFE_HARBOR_UNITS_INVALID"></a>

#### SAFE_HARBOR_UNITS_INVALID

HTTP 422. Retry the same request: no.

> The Safe Harbor units ({received}) are not valid for this opportunity ({available} available). Send a whole number from 1 to the available units.

<a id="error-EPC_OUT_OF_RANGE"></a>

#### EPC_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

> The {field} is the total EPC in US dollars, between {min} and {max}; {received} is outside that range. {hint}.

`epcAmount` is the total EPC for the system in US dollars, before tax: from 1,000 to 500,000. `hint` in the message says what the amount looks like (cents, a $/W price or an amount in thousands).

<a id="error-EPC_PER_WATT_OUT_OF_RANGE"></a>

#### EPC_PER_WATT_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

> The {field} {received} on a {systemSizeKw} kW DC system is {perWatt} per watt, outside the {min} to {max} per watt Participate Energy prices. Check that {field} is the total EPC in US dollars and systemSizeKw is the DC size in kW.

Only when you send `systemSizeKw`. PE checks that the EPC is from $1 to $10 per watt of DC size on a `solar_only` system, and at least $1 per watt on `solar_battery` (the EPC also pays for the battery; no upper limit). `battery_only` is not checked.

<a id="error-SYSTEM_SIZE_LOOKS_LIKE_WATTS"></a>

#### SYSTEM_SIZE_LOOKS_LIKE_WATTS

HTTP 422. Retry the same request: no.

> The {field} is in kW DC. {received} looks like watts; send {suggested}.

The API never converts units. `details[0].didYouMean` has the size in kW.

<a id="error-SYSTEM_SIZE_OUT_OF_RANGE"></a>

#### SYSTEM_SIZE_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

> System size is in kW DC, between {min} and {max}. The {field} {received} is outside that range.

<a id="error-CONTRACT_DATE_OUT_OF_RANGE"></a>

#### CONTRACT_DATE_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

> The contractDate {received} is outside the dates Participate Energy prices. Send a date from {min} to {max} (one year before today to 90 days after today), as YYYY-MM-DD.

Pricing takes a `contractDate` from one year before today to 90 days after today (today in US Pacific time). `details[0].min` and `details[0].max` have the dates.

<a id="error-CONTRACT_DATE_BEFORE_RETITC_CUTOFF"></a>

#### CONTRACT_DATE_BEFORE_RETITC_CUTOFF

HTTP 422. Retry the same request: no.

> The contractDate {received} is before {cutoff}, the date the Hawaii RETITC stopped being included. The API does not accept backdated Hawaii contracts; contact Participate Energy at raceway.support@participate.energy if this contract was signed before then.

A Hawaii `contractDate` before 2026-07-03 is refused. The Hawaii RETITC is an included incentive only for contracts signed before that date, so a backdated date would unlock an incentive that is no longer offered. If the contract was signed before 2026-07-03, contact Participate Energy. `details[0].received` has the date you sent.

<a id="error-AMOUNT_OUT_OF_RANGE"></a>

#### AMOUNT_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

> The {field} is an amount in US dollars, between {min} and {max}; {received} is outside that range. {hint}.

`POST /sales-tax`: `netAmountDue` must be from 1,000 to 500,000 US dollars. `0` counts as left out: the rate only, no amount.

<a id="error-ROOFING_COST_INVALID"></a>

#### ROOFING_COST_INVALID

HTTP 422. Retry the same request: no.

> The roofing costs are not valid: {reason}. Send amounts of 0 or more, in USD.

<a id="error-ROOFING_COST_NOT_APPLICABLE"></a>

#### ROOFING_COST_NOT_APPLICABLE

HTTP 422. Retry the same request: no.

> Roofing costs apply only to systems with solar. Send eligibleRoofingCost and ineligibleRoofingCost as 0, or leave them out, for a battery_only system.

<a id="error-INSURANCE_OPTION_INVALID"></a>

#### INSURANCE_OPTION_INVALID

HTTP 422. Retry the same request: no.

> The insuranceOption {received} is not available for this project. Send 1, 2 or 3.

PE reserves this code. The API does not return it today.

<a id="error-INCENTIVE_NOT_AVAILABLE"></a>

#### INCENTIVE_NOT_AVAILABLE

HTTP 422. Retry the same request: no.

> The included incentive {received} is not available for this installer or state. Send type "none", or an incentive that applies.

<a id="error-INCENTIVE_OUT_OF_RANGE"></a>

#### INCENTIVE_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

> The included incentive amount {received} is too large for an EPC of {epc}. The amount must be less than the EPC and leave a Net Amount Due of 0 or more. Check the amount, in US dollars.

<a id="error-SALES_TAX_UNRESOLVED"></a>

#### SALES_TAX_UNRESOLVED

HTTP 422. Retry the same request: no.

> The sales tax rate for this address could not be found. Check the address, or contact Participate Energy if it is correct.

<a id="error-SUNGAGE_PRODUCT_UNAVAILABLE"></a>

#### SUNGAGE_PRODUCT_UNAVAILABLE

HTTP 422. Retry the same request: no.

> The Sungage product, term or rate is not available for this installer and project. Use a combination from GET /v2/design/pricing/sungage/products.

<a id="error-PRODUCT_NOT_SUPPORTED"></a>

#### PRODUCT_NOT_SUPPORTED

HTTP 422. Retry the same request: no.

> The productType {received} is not supported by the Design API v2. Send "Synthetic Cash" or leave it out.

<a id="error-UPLOAD_FILE_MISSING"></a>

#### UPLOAD_FILE_MISSING

HTTP 422. Retry the same request: no.

> No file was found for upload {uploadId}. PUT the PDF to the uploadUrl first, then submit.

Check that the PUT sent every header in `uploadHeaders` and returned HTTP 200.

<a id="error-UPLOAD_NOT_PDF"></a>

#### UPLOAD_NOT_PDF

HTTP 422. Retry the same request: no.

> The file for upload {uploadId} is not a PDF. Upload the signed contract as a PDF with a new upload; you can use the same vendorProjectId.

The upload URL accepts one file only. Create a new upload with a new `vendorProjectId`, or wait until the first upload URL expires (15 minutes) and use the same `vendorProjectId` again.

<a id="error-UPLOAD_SIZE_MISMATCH"></a>

#### UPLOAD_SIZE_MISMATCH

HTTP 422. Retry the same request: no.

> The file for upload {uploadId} is {received} bytes, but the upload declared sizeBytes {expected}. Create a new upload with the file's exact size; you can use the same vendorProjectId.

The upload URL requires the exact `sizeBytes` you declared, so this happens only when the URL was signed before 2.2. Create a new upload with the file's exact size.

<a id="error-WEBHOOK_URL_PRIVATE_ADDRESS"></a>

#### WEBHOOK_URL_PRIVATE_ADDRESS

HTTP 422. Retry the same request: no.

> The webhook host {host} resolves to a private, local or reserved address. Use a host that resolves to public internet addresses only.

<a id="error-WEBHOOK_NOT_CONFIGURED"></a>

#### WEBHOOK_NOT_CONFIGURED

HTTP 422. Retry the same request: no.

> No webhook URL is set for the {environment} environment. Set one with PUT /v2/design/webhooks first.

### HTTP 429: limits

<a id="error-RATE_LIMITED"></a>

#### RATE_LIMITED

HTTP 429. Retry the same request: yes.

> Too many requests: the limit is {limit} {window}. Wait for the Retry-After seconds, then retry.

Wait the seconds in the `Retry-After` header. `details` give `limit`, `window` and `resetAt`.

<a id="error-DAILY_QUOTA_EXCEEDED"></a>

#### DAILY_QUOTA_EXCEEDED

HTTP 429. Retry the same request: yes.

> This installer connection used its daily limit of {limit} uploads in the {environment} environment. The limit resets at {resetAt}; retry after that.

The limit is for each grant and each environment, for each UTC day. `details` give `limit`, `window` and `resetAt`.

### HTTP 500, 503 and 504: server and upstream errors

<a id="error-EC_LOOKUP_UNAVAILABLE"></a>

#### EC_LOOKUP_UNAVAILABLE

HTTP 503. Retry the same request: yes.

> The Energy Community check is unavailable right now. Retry the same request in a few minutes, or send energyCommunity as true or false.

<a id="error-TAX_RATE_UNAVAILABLE"></a>

#### TAX_RATE_UNAVAILABLE

HTTP 503. Retry the same request: yes.

> The sales tax service is unavailable right now. Retry the same request in a few minutes.

<a id="error-ADDRESS_LOOKUP_UNAVAILABLE"></a>

#### ADDRESS_LOOKUP_UNAVAILABLE

HTTP 503. Retry the same request: yes.

> The address service is unavailable right now. Retry the same request in a few minutes.

Google Maps did not answer when PE looked up the site address for `POST /sales-tax` or `POST /tax-credits/energy-community`.

<a id="error-SUNGAGE_UNAVAILABLE"></a>

#### SUNGAGE_UNAVAILABLE

HTTP 503. Retry the same request: yes.

> Sungage is unavailable right now. Retry the same request in a few minutes.

<a id="error-UPSTREAM_TIMEOUT"></a>

#### UPSTREAM_TIMEOUT

HTTP 504. Retry the same request: yes.

> A service this request depends on did not answer in time. Retry the same request in a few minutes.

PE reserves this code. The API does not return it today.

<a id="error-SERVICE_DISABLED"></a>

#### SERVICE_DISABLED

HTTP 503. Retry the same request: yes.

> The Design API is temporarily turned off by Participate Energy. Retry later; see raceway.support@participate.energy for status.

<a id="error-INTERNAL_ERROR"></a>

#### INTERNAL_ERROR

HTTP 500. Retry the same request: yes.

> An unexpected error occurred while handling request {requestId}. Retry once; if it fails again, send the request id to raceway.support@participate.energy.

Quote `meta.requestId` when you contact PE.
