# Participate Energy Design API v2 (files/api/SPEC-design-api-v2.md section 12).
# Source of truth. openapi.json is generated from this file by
# scripts/gen-design-openapi-json.cjs; run it after every edit.
# The ErrorCode, UploadOutcome, Scope and PricingWarningCode enums and the
# operations are pinned to the code by functions/src/api/design/openapi.test.ts.
# Synthetic examples only: no real names, addresses, ids or secrets.
openapi: 3.1.0
info:
  title: Participate Energy Design API
  version: 2.2.0
  description: |-
    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.

    ## 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

    #### 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.

    #### 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.

    #### 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`.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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`.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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

    #### 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/.

    #### 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.

    #### 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.

    #### 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

    #### 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

    #### 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.

    #### 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.

    #### 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`.

    #### 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

    #### 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.

    #### 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.

    #### 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.

    #### 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

    #### 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.

    #### 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

    #### 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

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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`.

    #### 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`.

    #### 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.

    #### 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.

    #### 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.

    #### 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).

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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.

    #### 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

    #### 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`.

    #### 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

    #### 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.

    #### 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.

    #### 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`.

    #### SUNGAGE_UNAVAILABLE

    HTTP 503. Retry the same request: yes.

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

    #### 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.

    #### 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.

    #### 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.
  contact:
    name: Participate Energy API support
    email: raceway.support@participate.energy
  license:
    name: Proprietary
    url: https://participate.energy
servers:
  - url: https://api.participate.energy/v2/design
    description: Test and production. The client credential decides the environment.
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: |-
      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.
  - name: Connection
    description: |-
      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`.
  - name: AVL and reference data
    description: |-
      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.
  - name: Eligibility
    description: |-
      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.

      `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.

      `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.
  - name: Lease pricing
    description: |-
      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.
  - name: Sungage pricing
    description: |-
      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.
  - name: Contract uploads
    description: |-
      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.
  - name: Projects
    description: |-
      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.
  - name: Webhooks
    description: |-
      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", ""))
      ```
  - name: Sandbox
    description: |-
      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.
paths:
  /oauth/token:
    post:
      operationId: createAccessToken
      tags:
        - Authentication
      summary: Get an access token
      description: |-
        Trade your client credentials and a grant for a bearer token. The token lasts 60 minutes and is for one installer and one environment. Send the credentials with HTTP Basic or in the body. This endpoint also accepts the OAuth names grant_type, client_id, client_secret and grant_id, and a form body.

        **Scope:** none

        **Errors**

        | Code | HTTP | Retry |
        |---|---|---|
        | [`UNSUPPORTED_MEDIA_TYPE`](#error-UNSUPPORTED_MEDIA_TYPE) | 415 | no |
        | [`INVALID_JSON`](#error-INVALID_JSON) | 400 | no |
        | [`VALIDATION_FAILED`](#error-VALIDATION_FAILED) | 400 | no |
        | [`UNKNOWN_FIELD`](#error-UNKNOWN_FIELD) | 400 | no |
        | [`INVALID_CLIENT`](#error-INVALID_CLIENT) | 401 | no |
        | [`CLIENT_REVOKED`](#error-CLIENT_REVOKED) | 401 | no |
        | [`CLIENT_EXPIRED`](#error-CLIENT_EXPIRED) | 401 | no |
        | [`VENDOR_SUSPENDED`](#error-VENDOR_SUSPENDED) | 403 | no |
        | [`ENVIRONMENT_NOT_ENABLED`](#error-ENVIRONMENT_NOT_ENABLED) | 403 | no |
        | [`GRANT_NOT_FOUND`](#error-GRANT_NOT_FOUND) | 404 | no |
        | [`GRANT_REVOKED`](#error-GRANT_REVOKED) | 403 | no |
        | [`INTEGRATION_NOT_ENABLED`](#error-INTEGRATION_NOT_ENABLED) | 403 | no |
        | [`BODY_TOO_LARGE`](#error-BODY_TOO_LARGE) | 413 | no |
        | [`RATE_LIMITED`](#error-RATE_LIMITED) | 429 | yes |
        | [`SERVICE_DISABLED`](#error-SERVICE_DISABLED) | 503 | yes |
        | [`INTERNAL_ERROR`](#error-INTERNAL_ERROR) | 500 | yes |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenRequest"
            examples:
              basic:
                summary: Credentials in HTTP Basic
                value:
                  grantType: client_credentials
                  grantId: grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y
              body:
                summary: Credentials in the body
                value:
                  grantType: client_credentials
                  clientId: dc_test_Q7mN2pR8sT4vX1yZ3aB5cD6e
                  clientSecret: dcs_test_Zx8Cv7Bn6Mm5Ll4Kk3Jj2Hh1Gg0Ff9Ee8Dd7Cc6B
                  grantId: grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/TokenFormRequest"
      responses:
        "200":
          description: The access token.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
              examples:
                token:
                  summary: A Test token
                  value:
                    data:
                      accessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJwZS1kZXNpZ24tYXBpIiwic3ViIjoiZGNfdGVzdF9FWEFNUExFIn0.c2lnbmF0dXJlLWV4YW1wbGUtb25seQ
                      tokenType: Bearer
                      expiresIn: 3600
                      environment: test
                      scopes:
                        - avl:read
                        - eligibility:read
                        - pricing:lease
                        - pricing:sungage
                        - projects:create
                        - projects:read
                        - webhooks:manage
                      grantId: grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y
                      installer:
                        name: Sunbright Solar (example)
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: INVALID_CLIENT, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INVALID_CLIENT:
                  $ref: "#/components/examples/Error_INVALID_CLIENT"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - clientBasic: []
        - {}
      x-pe-scope: null
      x-pe-rate-limit-bucket: auth
  /connections/exchange:
    post:
      operationId: exchangeConnectionCode
      tags:
        - Authentication
      summary: Exchange a connection code for a grant
      description: |-
        Trade the one-time connection code from an installer for a grant. A code works once and expires 72 hours after the installer creates it. If you already have an active grant for this installer, PE revokes it and the new grant replaces it. Store the grantId.

        **Scope:** none

        **Errors**

        | Code | HTTP | Retry |
        |---|---|---|
        | [`UNSUPPORTED_MEDIA_TYPE`](#error-UNSUPPORTED_MEDIA_TYPE) | 415 | no |
        | [`INVALID_JSON`](#error-INVALID_JSON) | 400 | no |
        | [`VALIDATION_FAILED`](#error-VALIDATION_FAILED) | 400 | no |
        | [`UNKNOWN_FIELD`](#error-UNKNOWN_FIELD) | 400 | no |
        | [`INVALID_CLIENT`](#error-INVALID_CLIENT) | 401 | no |
        | [`CLIENT_REVOKED`](#error-CLIENT_REVOKED) | 401 | no |
        | [`CLIENT_EXPIRED`](#error-CLIENT_EXPIRED) | 401 | no |
        | [`VENDOR_SUSPENDED`](#error-VENDOR_SUSPENDED) | 403 | no |
        | [`ENVIRONMENT_NOT_ENABLED`](#error-ENVIRONMENT_NOT_ENABLED) | 403 | no |
        | [`CONNECTION_CODE_INVALID`](#error-CONNECTION_CODE_INVALID) | 400 | no |
        | [`CONNECTION_CODE_WRONG_VENDOR`](#error-CONNECTION_CODE_WRONG_VENDOR) | 422 | no |
        | [`CONNECTION_CODE_USED`](#error-CONNECTION_CODE_USED) | 409 | no |
        | [`CONNECTION_CODE_REVOKED`](#error-CONNECTION_CODE_REVOKED) | 410 | no |
        | [`CONNECTION_CODE_EXPIRED`](#error-CONNECTION_CODE_EXPIRED) | 410 | no |
        | [`INTEGRATION_NOT_ENABLED`](#error-INTEGRATION_NOT_ENABLED) | 403 | no |
        | [`NO_SCOPES_AVAILABLE`](#error-NO_SCOPES_AVAILABLE) | 422 | no |
        | [`BODY_TOO_LARGE`](#error-BODY_TOO_LARGE) | 413 | no |
        | [`RATE_LIMITED`](#error-RATE_LIMITED) | 429 | yes |
        | [`SERVICE_DISABLED`](#error-SERVICE_DISABLED) | 503 | yes |
        | [`INTERNAL_ERROR`](#error-INTERNAL_ERROR) | 500 | yes |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExchangeRequest"
            examples:
              basic:
                summary: Credentials in HTTP Basic
                value:
                  connectionCode: pec_k7m2q4x5r3t6w2y5z7b3c6d7fg
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/ExchangeRequest"
      responses:
        "200":
          description: The new grant.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExchangeResponse"
              examples:
                grant:
                  summary: A new grant
                  value:
                    data:
                      grantId: grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y
                      installer:
                        name: Sunbright Solar (example)
                      scopes:
                        - avl:read
                        - eligibility:read
                        - pricing:lease
                        - pricing:sungage
                        - projects:create
                        - projects:read
                        - webhooks:manage
                      createdAt: "2026-11-10T18:02:11.482Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD, CONNECTION_CODE_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
                CONNECTION_CODE_INVALID:
                  $ref: "#/components/examples/Error_CONNECTION_CODE_INVALID"
        "401":
          description: "Authentication failed. Codes: INVALID_CLIENT, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INVALID_CLIENT:
                  $ref: "#/components/examples/Error_INVALID_CLIENT"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INTEGRATION_NOT_ENABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
        "409":
          description: "Conflict. Codes: CONNECTION_CODE_USED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                CONNECTION_CODE_USED:
                  $ref: "#/components/examples/Error_CONNECTION_CODE_USED"
        "410":
          description: "Gone. Codes: CONNECTION_CODE_REVOKED, CONNECTION_CODE_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                CONNECTION_CODE_REVOKED:
                  $ref: "#/components/examples/Error_CONNECTION_CODE_REVOKED"
                CONNECTION_CODE_EXPIRED:
                  $ref: "#/components/examples/Error_CONNECTION_CODE_EXPIRED"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: CONNECTION_CODE_WRONG_VENDOR, NO_SCOPES_AVAILABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                CONNECTION_CODE_WRONG_VENDOR:
                  $ref: "#/components/examples/Error_CONNECTION_CODE_WRONG_VENDOR"
                NO_SCOPES_AVAILABLE:
                  $ref: "#/components/examples/Error_NO_SCOPES_AVAILABLE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - clientBasic: []
        - {}
      x-pe-scope: null
      x-pe-rate-limit-bucket: auth
  /grant:
    get:
      operationId: getGrant
      tags:
        - Connection
      summary: Read the grant
      description: |-
        Read the grant behind your token.

        **Scope:** none

        **Errors** (and the common errors listed in Errors)

        This endpoint has no other error codes.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The grant.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GrantResponse"
              examples:
                grant:
                  summary: An active grant
                  value:
                    data:
                      grantId: grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y
                      installer:
                        name: Sunbright Solar (example)
                      scopes:
                        - avl:read
                        - eligibility:read
                        - pricing:lease
                        - pricing:sungage
                        - projects:create
                        - projects:read
                        - webhooks:manage
                      environment: test
                      createdAt: "2026-11-03T15:20:44.000Z"
                      status: active
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth: []
      x-pe-scope: null
      x-pe-rate-limit-bucket: read
    delete:
      operationId: revokeGrant
      tags:
        - Connection
      summary: Revoke the grant
      description: |-
        End your connection to this installer. Tokens for the grant stop working within 60 seconds. To connect again, the installer must create a new connection code. A repeat call returns the same answer.

        **Scope:** none

        **Errors** (and the common errors listed in Errors)

        This endpoint has no other error codes.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The grant is revoked.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GrantRevokedResponse"
              examples:
                revoked:
                  summary: Revoked
                  value:
                    data:
                      grantId: grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y
                      status: revoked
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth: []
      x-pe-scope: null
      x-pe-rate-limit-bucket: write
  /ping:
    get:
      operationId: ping
      tags:
        - Connection
      summary: Check the token
      description: |-
        Check that your token works. The response shows the environment, your vendor code, the installer and your scopes.

        **Scope:** none

        **Errors** (and the common errors listed in Errors)

        This endpoint has no other error codes.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The token works.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PingResponse"
              examples:
                ok:
                  summary: A Test token
                  value:
                    data:
                      ok: true
                      environment: test
                      vendor: aurora
                      installer:
                        name: Sunbright Solar (example)
                      scopes:
                        - avl:read
                        - eligibility:read
                        - pricing:lease
                        - pricing:sungage
                        - projects:create
                        - projects:read
                        - webhooks:manage
                      tokenExpiresAt: "2026-11-10T19:02:11.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth: []
      x-pe-scope: null
      x-pe-rate-limit-bucket: read
  /avl:
    get:
      operationId: listAvl
      tags:
        - AVL and reference data
      summary: List AVL equipment
      description: |-
        List the equipment on PE's Approved Vendor List, sorted by category, manufacturer and SKU. Default 100 items for each page, at most 500.

        **Scope:** `avl:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`VALIDATION_FAILED`](#error-VALIDATION_FAILED) | 400 | no |
        | [`UNKNOWN_FIELD`](#error-UNKNOWN_FIELD) | 400 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: category
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/AvlCategory"
          example: pv_module
        - name: search
          in: query
          required: false
          description: Text to find in the SKU, manufacturer or description.
          schema:
            type: string
            minLength: 1
            maxLength: 100
          example: Qcells
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
          example: 100
        - name: cursor
          in: query
          required: false
          description: nextCursor from the previous page.
          schema:
            type: string
            maxLength: 200
      responses:
        "200":
          description: One page of items.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AvlPageResponse"
              examples:
                page:
                  summary: A page of modules
                  value:
                    data:
                      avlVersionId: avl_v_2026_10_28
                      items:
                        - sku: Q.TRON BLK M-G2+ 425
                          category: pv_module
                          manufacturer: Qcells
                          model: Q.TRON BLK M-G2+
                          description: Qcells Q.TRON BLK M-G2+ 425W
                          domesticContent:
                            module: 0.62
                            inverter: 0
                        - sku: IQ8X-80-M-US
                          category: pv_inverter
                          manufacturer: Enphase
                          model: IQ8X
                          description: Enphase IQ8X Microinverter
                          domesticContent:
                            module: 0
                            inverter: 0.41
                      nextCursor: eyJ2IjoiYXZsX3ZfMjAyNl8xMF8yOCIsIm8iOjEwMH0
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
  /safe-harbor/opportunities:
    get:
      operationId: listSafeHarborOpportunities
      tags:
        - AVL and reference data
      summary: List Safe Harbor opportunities
      description: |-
        List the installer's Safe Harbor opportunities that carry a deduction in pricing.

        **Scope:** `avl:read`

        **Errors** (and the common errors listed in Errors)

        This endpoint has no other error codes.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The opportunities.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SafeHarborOpportunityListResponse"
              examples:
                list:
                  summary: One opportunity
                  value:
                    data:
                      opportunities:
                        - opportunityId: SHO-2025-D-0142
                          name: 2025 Module Safe Harbor Program
                          unitCost: 4.68
                          unitsAvailable: 120
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
  /safe-harbor/opportunities/{opportunityId}/avl:
    get:
      operationId: listSafeHarborOpportunityAvl
      tags:
        - AVL and reference data
      summary: List an opportunity's custom AVL
      description: |-
        List the active custom AVL items of one of the installer's Safe Harbor opportunities. Domestic Content values are fractions, as in GET /avl.

        **Scope:** `avl:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND) | 404 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: opportunityId
          in: path
          required: true
          description: The opportunity id from GET /safe-harbor/opportunities.
          schema:
            type: string
          example: SHO-2025-D-0142
      responses:
        "200":
          description: The custom AVL items.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomAvlListResponse"
              examples:
                list:
                  summary: Custom items
                  value:
                    data:
                      opportunityId: SHO-2025-D-0142
                      items:
                        - skuPattern: SH25-MOD-*
                          category: pv_module
                          manufacturer: Example Solar Manufacturing
                          product: SH25 410W
                          typeRef: null
                          domesticContent:
                            module: 0.68
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, SAFE_HARBOR_OPPORTUNITY_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
  /states:
    get:
      operationId: listStates
      tags:
        - AVL and reference data
      summary: List the installer's states
      description: |-
        List the states where PE operates and the installer is active, and the PE products enabled for the installer.

        **Scope:** `avl:read`

        **Errors** (and the common errors listed in Errors)

        This endpoint has no other error codes.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The states.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StateListResponse"
              examples:
                states:
                  summary: Two states
                  value:
                    data:
                      states:
                        - stateCode: CA
                          name: California
                        - stateCode: TX
                          name: Texas
                      enabledProducts:
                        - Synthetic Cash
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
  /utilities:
    get:
      operationId: listUtilitiesByZip
      tags:
        - AVL and reference data
      summary: List the utilities of a ZIP code
      description: |-
        List the utilities that serve a ZIP code. Use a `name` from this list as `utility` in `POST /eligibility`.

        `primary` is true for the main utility of the ZIP code. The list shows the primary utility first. A ZIP code that PE does not know returns `stateCode: null` and an empty list.

        **Scope:** `avl:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`VALIDATION_FAILED`](#error-VALIDATION_FAILED) | 400 | no |
        | [`UNKNOWN_FIELD`](#error-UNKNOWN_FIELD) | 400 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: zipCode
          in: query
          required: true
          description: The ZIP code of the site, 5 digits or ZIP+4. PE uses the first 5 digits. Not 00000.
          schema:
            type: string
            pattern: ^[0-9]{5}(-[0-9]{4})?$
          example: "78701"
      responses:
        "200":
          description: The utilities.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UtilityListResponse"
              examples:
                list:
                  summary: Utilities of ZIP code 78701
                  value:
                    data:
                      zipCode: "78701"
                      stateCode: TX
                      utilities:
                        - utilityId: util_tx_0042
                          name: Austin Energy
                          primary: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
  /utilities/{stateCode}:
    get:
      operationId: listUtilities
      tags:
        - AVL and reference data
      summary: List the utilities of a state (retired)
      deprecated: true
      description: |-
        Retired in 2.1. PE no longer lists the utilities of a whole state. This path always returns 410 `UTILITY_LIST_BY_STATE_RETIRED`. Use `GET /utilities?zipCode=`.

        **Scope:** `avl:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`UTILITY_LIST_BY_STATE_RETIRED`](#error-UTILITY_LIST_BY_STATE_RETIRED) | 410 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: stateCode
          in: path
          required: true
          description: A 2-letter US state code.
          schema:
            type: string
            pattern: ^[A-Za-z]{2}$
          example: TX
      responses:
        "410":
          description: "Gone. Codes: UTILITY_LIST_BY_STATE_RETIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UTILITY_LIST_BY_STATE_RETIRED:
                  $ref: "#/components/examples/Error_UTILITY_LIST_BY_STATE_RETIRED"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
  /eligibility:
    post:
      operationId: checkEligibility
      tags:
        - Eligibility
      summary: Check site eligibility
      description: |-
        Run PE's eligibility rules for a site. Failed rules are checks in the response, not errors.

        **Scope:** `eligibility:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US) | 422 | no |
        | [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EligibilityRequest"
            examples:
              site:
                summary: A townhome in Texas
                value:
                  address:
                    street: 100 Example Street
                    city: Austin
                    stateCode: TX
                    zipCode: "78701"
                  homeType: townhome
                  ownership: owner
                  existingSolarOnProperty: none
                  utility: Austin Energy
                  systemType: solar_battery
      responses:
        "200":
          description: The checks.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EligibilityResponse"
              examples:
                eligible:
                  summary: Eligible
                  value:
                    data:
                      eligible: true
                      stateCode: TX
                      systemType: solar_battery
                      checks:
                        - check: state
                          result: pass
                          message: Participate Energy operates in Texas.
                        - check: installer_state
                          result: pass
                          message: The installer is active in Texas.
                        - check: product
                          result: pass
                          message: The Participate Energy lease (Synthetic Cash) is enabled for the installer.
                        - check: utility
                          result: pass
                          message: The utility serves Texas.
                        - check: home_type
                          result: pass
                          message: A townhome qualifies when the customer owns the roof.
                        - check: ownership
                          result: pass
                          message: The customer owns the home.
                        - check: existing_solar
                          result: pass
                          message: There is no existing solar system.
                        - check: address
                          result: pass
                          message: The address was found in Texas.
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
                renter:
                  summary: "Not eligible: renter"
                  value:
                    data:
                      eligible: false
                      stateCode: TX
                      systemType: solar_only
                      checks:
                        - check: state
                          result: pass
                          message: Participate Energy operates in Texas.
                        - check: installer_state
                          result: pass
                          message: The installer is active in Texas.
                        - check: product
                          result: pass
                          message: The Participate Energy lease (Synthetic Cash) is enabled for the installer.
                        - check: ownership
                          result: fail
                          code: OWNERSHIP_NOT_ELIGIBLE
                          message: The customer must own the home (fee simple ownership). A renter does not qualify.
                        - check: address
                          result: pass
                          message: The address was found in Texas.
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: ADDRESS_OUTSIDE_US, ADDRESS_PO_BOX."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ADDRESS_OUTSIDE_US:
                  $ref: "#/components/examples/Error_ADDRESS_OUTSIDE_US"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - eligibility:read
      x-pe-scope: eligibility:read
      x-pe-rate-limit-bucket: read
  /tax-credits/domestic-content:
    post:
      operationId: checkDomesticContent
      tags:
        - Eligibility
      summary: Check Domestic Content
      description: |-
        Check equipment against PE's AVL and the Domestic Content thresholds. 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.

        **Scope:** `eligibility:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND) | 404 | no |
        | [`EQUIPMENT_NOT_ON_AVL`](#error-EQUIPMENT_NOT_ON_AVL) | 422 | no |
        | [`EQUIPMENT_AMBIGUOUS`](#error-EQUIPMENT_AMBIGUOUS) | 422 | no |
        | [`EQUIPMENT_CATEGORY_MISMATCH`](#error-EQUIPMENT_CATEGORY_MISMATCH) | 422 | no |
        | [`EQUIPMENT_QUANTITY_OUT_OF_RANGE`](#error-EQUIPMENT_QUANTITY_OUT_OF_RANGE) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DomesticContentRequest"
            examples:
              pv:
                summary: Modules, inverters and a battery
                value:
                  equipment:
                    - sku: Q.TRON BLK M-G2+ 425
                      category: pv_module
                      quantity: 24
                    - sku: IQ8X-80-M-US
                      category: pv_inverter
                      quantity: 24
                    - sku: XYZ-BATT-EXAMPLE
                      category: bess
                      quantity: 1
                  year: 2026
      responses:
        "200":
          description: The result.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DomesticContentResponse"
              examples:
                result:
                  summary: PV meets the threshold; one item does not match
                  value:
                    data:
                      year: 2026
                      thresholdBasis: computeYear
                      bocDate: null
                      pv:
                        included: true
                        eligible: true
                        percent: 52.4
                        threshold: 50
                      storage:
                        included: false
                        eligible: false
                        percent: null
                        threshold: 55
                      feoc:
                        applies: true
                        pv:
                          included: true
                          eligible: true
                          percent: 48.5
                          threshold: 40
                        storage:
                          included: false
                          eligible: false
                          percent: null
                          threshold: 55
                      items:
                        - sku: Q.TRON BLK M-G2+ 425
                          category: pv_module
                          quantity: 24
                          resolved: true
                          source: avl
                          manufacturer: Qcells
                          description: Qcells Q.TRON BLK M-G2+ 425W
                          dcPercent: 62
                          feocPercent: 31
                        - sku: IQ8X-80-M-US
                          category: pv_inverter
                          quantity: 24
                          resolved: true
                          source: avl
                          manufacturer: Enphase
                          description: Enphase IQ8X Microinverter
                          dcPercent: 41
                          feocPercent: 17.5
                        - sku: XYZ-BATT-EXAMPLE
                          category: bess
                          quantity: 1
                          resolved: false
                          source: null
                          code: EQUIPMENT_NOT_ON_AVL
                      unresolved:
                        - sku: XYZ-BATT-EXAMPLE
                          category: bess
                          code: EQUIPMENT_NOT_ON_AVL
                          message: This SKU is not on the approved vendor list.
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, SAFE_HARBOR_OPPORTUNITY_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: EQUIPMENT_NOT_ON_AVL, EQUIPMENT_AMBIGUOUS, EQUIPMENT_CATEGORY_MISMATCH, EQUIPMENT_QUANTITY_OUT_OF_RANGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                EQUIPMENT_NOT_ON_AVL:
                  $ref: "#/components/examples/Error_EQUIPMENT_NOT_ON_AVL"
                EQUIPMENT_AMBIGUOUS:
                  $ref: "#/components/examples/Error_EQUIPMENT_AMBIGUOUS"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - eligibility:read
      x-pe-scope: eligibility:read
      x-pe-rate-limit-bucket: read
  /tax-credits/energy-community:
    post:
      operationId: checkEnergyCommunity
      tags:
        - Eligibility
      summary: Check Energy Community
      description: |-
        Check whether the site is in an Energy Community.

        PE first finds the site address with Google Maps, then runs the check on the address Google returns. `resolvedAddress` shows that address. 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.

        **Scope:** `eligibility:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US) | 422 | no |
        | [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND) | 422 | no |
        | [`STATE_MISMATCH`](#error-STATE_MISMATCH) | 422 | no |
        | [`ADDRESS_LOOKUP_UNAVAILABLE`](#error-ADDRESS_LOOKUP_UNAVAILABLE) | 503 | yes |
        | [`EC_LOOKUP_UNAVAILABLE`](#error-EC_LOOKUP_UNAVAILABLE) | 503 | yes |
        | [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnergyCommunityRequest"
            examples:
              site:
                summary: A Texas site
                value:
                  address:
                    street: 100 Example Street
                    city: Austin
                    stateCode: TX
                    zipCode: "78701"
      responses:
        "200":
          description: The result.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnergyCommunityResponse"
              examples:
                qualifies:
                  summary: Qualifies
                  value:
                    data:
                      qualifies: true
                      category: statistical_area
                      itcBonus: 10
                      countyFips: "48453"
                      tractGeoid: "48453001100"
                      resolvedAddress:
                        formatted: 100 Example St, Austin, TX 78701, USA
                        street: 100 Example St
                        city: Austin
                        stateCode: TX
                        zipCode: "78701"
                        county: Travis
                        latitude: 30.2672
                        longitude: -97.7431
                        precision: rooftop
                        partialMatch: false
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: ADDRESS_OUTSIDE_US, ADDRESS_NOT_FOUND, STATE_MISMATCH, ADDRESS_PO_BOX."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ADDRESS_OUTSIDE_US:
                  $ref: "#/components/examples/Error_ADDRESS_OUTSIDE_US"
                ADDRESS_NOT_FOUND:
                  $ref: "#/components/examples/Error_ADDRESS_NOT_FOUND"
                STATE_MISMATCH:
                  $ref: "#/components/examples/Error_STATE_MISMATCH"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED, ADDRESS_LOOKUP_UNAVAILABLE, EC_LOOKUP_UNAVAILABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
                ADDRESS_LOOKUP_UNAVAILABLE:
                  $ref: "#/components/examples/Error_ADDRESS_LOOKUP_UNAVAILABLE"
                EC_LOOKUP_UNAVAILABLE:
                  $ref: "#/components/examples/Error_EC_LOOKUP_UNAVAILABLE"
      security:
        - bearerAuth: []
        - peOAuth:
            - eligibility:read
      x-pe-scope: eligibility:read
      x-pe-rate-limit-bucket: read
  /sales-tax:
    post:
      operationId: checkSalesTax
      tags:
        - Eligibility
      summary: Read the lease sales tax rate
      description: |-
        Read 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.

        PE first finds the site address with Google Maps, then reads the rate for the address Google returns. `resolvedAddress` shows that address. Outside Colorado, Google must place at least the street. When Google places the street but not the house number, PE reads the rate with the street line you sent and the city, state and ZIP code that Google found. Then `resolvedAddress.precision` is `street` and `jurisdiction.lowConfidence` is `true`. In Colorado, Google must place the street address with its house number, because the Colorado state lookup needs it. When Google finds only a city, a ZIP code or an area, the response is `ADDRESS_NOT_FOUND`, and `details[0].closestMatch` has the place Google matched.

        **Scope:** `eligibility:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US) | 422 | no |
        | [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND) | 422 | no |
        | [`STATE_MISMATCH`](#error-STATE_MISMATCH) | 422 | no |
        | [`SALES_TAX_UNRESOLVED`](#error-SALES_TAX_UNRESOLVED) | 422 | no |
        | [`TAX_RATE_UNAVAILABLE`](#error-TAX_RATE_UNAVAILABLE) | 503 | yes |
        | [`ADDRESS_LOOKUP_UNAVAILABLE`](#error-ADDRESS_LOOKUP_UNAVAILABLE) | 503 | yes |
        | [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX) | 422 | no |
        | [`AMOUNT_OUT_OF_RANGE`](#error-AMOUNT_OUT_OF_RANGE) | 422 | no |
        | [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SalesTaxCheckRequest"
            examples:
              site:
                summary: A Texas site
                value:
                  address:
                    street: 100 Example Street
                    city: Austin
                    stateCode: TX
                    zipCode: "78701"
                  systemType: solar_only
                  netAmountDue: 21000
      responses:
        "200":
          description: The result.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SalesTaxCheckResponse"
              examples:
                taxable:
                  summary: A Texas site
                  value:
                    data:
                      stateCode: TX
                      taxStateCode: TX
                      systemType: solar_only
                      taxable: true
                      rate: 0.0825
                      baseRate: 0.0825
                      grossedUp: false
                      netAmountDue: 21000
                      amount: 1732.5
                      source: STC
                      jurisdiction:
                        city: Austin
                        county: Travis
                        zipCode: "78701"
                        lowConfidence: false
                      components:
                        - name: State
                          type: State
                          rate: 0.0625
                          applied: true
                        - name: Travis
                          type: County
                          rate: 0
                          applied: true
                        - name: Austin
                          type: City
                          rate: 0.02
                          applied: true
                      asOfDate: "2026-11-12"
                      note: null
                      resolvedAddress:
                        formatted: 100 Example St, Austin, TX 78701, USA
                        street: 100 Example St
                        city: Austin
                        stateCode: TX
                        zipCode: "78701"
                        county: Travis
                        latitude: 30.2672
                        longitude: -97.7431
                        precision: rooftop
                        partialMatch: false
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: ADDRESS_OUTSIDE_US, ADDRESS_NOT_FOUND, STATE_MISMATCH, SALES_TAX_UNRESOLVED, ADDRESS_PO_BOX, AMOUNT_OUT_OF_RANGE, STATE_NOT_SUPPORTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ADDRESS_OUTSIDE_US:
                  $ref: "#/components/examples/Error_ADDRESS_OUTSIDE_US"
                ADDRESS_NOT_FOUND:
                  $ref: "#/components/examples/Error_ADDRESS_NOT_FOUND"
                STATE_MISMATCH:
                  $ref: "#/components/examples/Error_STATE_MISMATCH"
                SALES_TAX_UNRESOLVED:
                  $ref: "#/components/examples/Error_SALES_TAX_UNRESOLVED"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED, TAX_RATE_UNAVAILABLE, ADDRESS_LOOKUP_UNAVAILABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
                TAX_RATE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_TAX_RATE_UNAVAILABLE"
                ADDRESS_LOOKUP_UNAVAILABLE:
                  $ref: "#/components/examples/Error_ADDRESS_LOOKUP_UNAVAILABLE"
      security:
        - bearerAuth: []
        - peOAuth:
            - eligibility:read
      x-pe-scope: eligibility:read
      x-pe-rate-limit-bucket: read
  /pricing/lease:
    post:
      operationId: priceLease
      tags:
        - Lease pricing
      summary: Price a PE lease
      description: |-
        Price a PE lease. See How PE prices a lease in the Lease pricing section. The quote never creates a project.

        **Scope:** `pricing:lease`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US) | 422 | no |
        | [`EPC_OUT_OF_RANGE`](#error-EPC_OUT_OF_RANGE) | 422 | no |
        | [`ROOFING_COST_INVALID`](#error-ROOFING_COST_INVALID) | 422 | no |
        | [`INCENTIVE_NOT_AVAILABLE`](#error-INCENTIVE_NOT_AVAILABLE) | 422 | no |
        | [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED) | 422 | no |
        | [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND) | 404 | no |
        | [`SAFE_HARBOR_UNITS_INVALID`](#error-SAFE_HARBOR_UNITS_INVALID) | 422 | no |
        | [`STATE_MISMATCH`](#error-STATE_MISMATCH) | 422 | no |
        | [`SALES_TAX_UNRESOLVED`](#error-SALES_TAX_UNRESOLVED) | 422 | no |
        | [`TAX_RATE_UNAVAILABLE`](#error-TAX_RATE_UNAVAILABLE) | 503 | yes |
        | [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND) | 422 | no |
        | [`EC_LOOKUP_UNAVAILABLE`](#error-EC_LOOKUP_UNAVAILABLE) | 503 | yes |
        | [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX) | 422 | no |
        | [`EPC_PER_WATT_OUT_OF_RANGE`](#error-EPC_PER_WATT_OUT_OF_RANGE) | 422 | no |
        | [`SYSTEM_SIZE_LOOKS_LIKE_WATTS`](#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS) | 422 | no |
        | [`SYSTEM_SIZE_OUT_OF_RANGE`](#error-SYSTEM_SIZE_OUT_OF_RANGE) | 422 | no |
        | [`CONTRACT_DATE_OUT_OF_RANGE`](#error-CONTRACT_DATE_OUT_OF_RANGE) | 422 | no |
        | [`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`](#error-CONTRACT_DATE_BEFORE_RETITC_CUTOFF) | 422 | no |
        | [`INCENTIVE_OUT_OF_RANGE`](#error-INCENTIVE_OUT_OF_RANGE) | 422 | no |
        | [`ROOFING_COST_NOT_APPLICABLE`](#error-ROOFING_COST_NOT_APPLICABLE) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LeasePriceRequest"
            examples:
              texas:
                summary: Solar and battery in Texas, with roofing
                value:
                  epcAmount: 42000
                  eligibleRoofingCost: 5000
                  ineligibleRoofingCost: 3000
                  systemType: solar_battery
                  insuranceOption: 1
                  address:
                    street: 100 Example Street
                    city: Austin
                    stateCode: TX
                    zipCode: "78701"
                  pvDomesticContent: false
                  storageDomesticContent: false
                  energyCommunity: auto
                  dcBonusRecipient: customer
                  contractDate: "2026-11-10"
              california:
                summary: Solar in California, insurance option 3, installer keeps the DC bonus, Safe Harbor
                value:
                  epcAmount: 36500
                  systemType: solar_only
                  insuranceOption: 3
                  address:
                    street: 250 Sample Avenue
                    city: Fresno
                    stateCode: CA
                    zipCode: "93721"
                  pvDomesticContent: true
                  storageDomesticContent: false
                  energyCommunity: false
                  dcBonusRecipient: installer
                  safeHarbor:
                    opportunityId: SHO-2025-D-0142
                    units: 20
                  contractDate: "2026-11-10"
      responses:
        "200":
          description: The quote.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeaseQuoteResponse"
              examples:
                texas:
                  summary: Texas quote (sales tax applies)
                  value:
                    data:
                      quoteId: qte_6Gd2Hs8Kf3Lj7Qw9Er1T
                      leaseFactor: 1.4285714
                      leaseDiscountPercent: 30
                      tierLeaseFactor: 1.4285714
                      insuranceRiskAdjustment: 0
                      adjustedEpc: 47000
                      replacementCost: 50000
                      leaseDiscount: 14100
                      netAmountDue: 35900
                      leaseAmount: 35900
                      salesTax:
                        rate: 0.0825
                        amount: 2961.75
                        taxable: true
                        source: STC
                        needsAttention: null
                      insuranceRiderAmount: 0
                      dcBonusAmount: 0
                      safeHarborDeduction: 0
                      pePayout: 14100
                      icPaymentGross: 9400
                      icPayment: 6438.25
                      pcPayment: 4700
                      inputsEcho:
                        epcAmount: 42000
                        eligibleRoofingCost: 5000
                        ineligibleRoofingCost: 3000
                        systemType: solar_battery
                        insuranceOption: 1
                        address:
                          city: Austin
                          stateCode: TX
                          zipCode: "78701"
                        taxStateCode: TX
                        pvDomesticContent: false
                        storageDomesticContent: false
                        energyCommunity: true
                        energyCommunitySource: ec_check
                        energyCommunityCategory: statistical_area
                        dcBonusRecipient: customer
                        includedIncentive:
                          type: none
                          amount: 0
                        safeHarbor: null
                        existingSolarOnProperty: false
                        contractDate: "2026-11-10"
                      notes:
                        - Eligible roofing ($5,000.00) is added to the EPC basis, so the lease discount applies to it.
                        - Ineligible roofing ($3,000.00) passes through to the customer with no discount.
                        - "Lease discount: 30% of the Adjusted EPC ($47,000.00) is $14,100.00. The customer pays the replacement cost less this discount."
                        - Lease sales tax of 8.25% on the Net Amount Due is $2,961.75. The installer collects it from the customer on top of the Net Amount Due, and it is deducted from the Inspection Complete payment.
                        - PE pays the installer $6,438.25 at Inspection Complete (2/3 of the payout after Safe Harbor, less any deductions) and $4,700.00 at Project Complete (1/3).
                      warnings: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
                california:
                  summary: California quote with a state warning
                  value:
                    data:
                      quoteId: qte_6Gd2Hs8Kf3Lj7Qw9Er1T
                      leaseFactor: 1.4285714
                      leaseDiscountPercent: 30
                      tierLeaseFactor: 1.5384615
                      insuranceRiskAdjustment: 912.5
                      adjustedEpc: 37412.5
                      replacementCost: 37412.5
                      leaseDiscount: 11223.75
                      netAmountDue: 26188.75
                      leaseAmount: 26188.75
                      salesTax:
                        rate: 0
                        amount: 0
                        taxable: false
                        source: STC
                        needsAttention: null
                      insuranceRiderAmount: 912.5
                      dcBonusAmount: 1870.62
                      safeHarborDeduction: 93.6
                      pePayout: 13094.37
                      icPaymentGross: 8667.18
                      icPayment: 7754.68
                      pcPayment: 4333.59
                      inputsEcho:
                        epcAmount: 36500
                        eligibleRoofingCost: 0
                        ineligibleRoofingCost: 0
                        systemType: solar_only
                        insuranceOption: 3
                        address:
                          city: Fresno
                          stateCode: CA
                          zipCode: "93721"
                        taxStateCode: CA
                        pvDomesticContent: true
                        storageDomesticContent: false
                        energyCommunity: false
                        energyCommunitySource: request
                        energyCommunityCategory: null
                        dcBonusRecipient: installer
                        includedIncentive:
                          type: none
                          amount: 0
                        safeHarbor:
                          opportunityId: SHO-2025-D-0142
                          units: 20
                          unitCost: 4.68
                        existingSolarOnProperty: false
                        contractDate: "2026-11-10"
                      notes:
                        - Insurance option 3 raises the EPC basis by 2.5% ($912.50) before the lease math.
                        - "Lease discount: 30% of the Adjusted EPC ($37,412.50) is $11,223.75. The customer pays the replacement cost less this discount."
                        - "The Domestic Content bonus stays with the installer: the customer gets the baseline discount and the installer receives $1,870.62 more in the PE payout."
                        - Safe Harbor equipment ($93.60) reduces the PE payout before the split, so the installer bears 2/3 of it at Inspection Complete and 1/3 at Project Complete.
                        - No lease sales tax applies at this address for this system type.
                        - Insurance option 3 deducts a Risk-Based Pool contribution of 2.5% of the EPC ($912.50) from the Inspection Complete payment.
                        - PE pays the installer $7,754.68 at Inspection Complete (2/3 of the payout after Safe Harbor, less any deductions) and $4,333.59 at Project Complete (1/3).
                      warnings:
                        - code: STATE_NOT_ACTIVE_FOR_INSTALLER
                          message: The installer is not active in California yet, so it cannot submit a contract for this project until the state is active. The installer can request the state in the Installer Portal. The prices below are still correct.
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, SAFE_HARBOR_OPPORTUNITY_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: ADDRESS_OUTSIDE_US, EPC_OUT_OF_RANGE, ROOFING_COST_INVALID, INCENTIVE_NOT_AVAILABLE, STATE_NOT_SUPPORTED, SAFE_HARBOR_UNITS_INVALID, STATE_MISMATCH, SALES_TAX_UNRESOLVED, ADDRESS_NOT_FOUND, ADDRESS_PO_BOX, EPC_PER_WATT_OUT_OF_RANGE, SYSTEM_SIZE_LOOKS_LIKE_WATTS, SYSTEM_SIZE_OUT_OF_RANGE, CONTRACT_DATE_OUT_OF_RANGE, CONTRACT_DATE_BEFORE_RETITC_CUTOFF, INCENTIVE_OUT_OF_RANGE, ROOFING_COST_NOT_APPLICABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ADDRESS_OUTSIDE_US:
                  $ref: "#/components/examples/Error_ADDRESS_OUTSIDE_US"
                EPC_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EPC_OUT_OF_RANGE"
                ROOFING_COST_INVALID:
                  $ref: "#/components/examples/Error_ROOFING_COST_INVALID"
                INCENTIVE_NOT_AVAILABLE:
                  $ref: "#/components/examples/Error_INCENTIVE_NOT_AVAILABLE"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
                SAFE_HARBOR_UNITS_INVALID:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_UNITS_INVALID"
                STATE_MISMATCH:
                  $ref: "#/components/examples/Error_STATE_MISMATCH"
                SALES_TAX_UNRESOLVED:
                  $ref: "#/components/examples/Error_SALES_TAX_UNRESOLVED"
                ADDRESS_NOT_FOUND:
                  $ref: "#/components/examples/Error_ADDRESS_NOT_FOUND"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED, TAX_RATE_UNAVAILABLE, EC_LOOKUP_UNAVAILABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
                TAX_RATE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_TAX_RATE_UNAVAILABLE"
                EC_LOOKUP_UNAVAILABLE:
                  $ref: "#/components/examples/Error_EC_LOOKUP_UNAVAILABLE"
      security:
        - bearerAuth: []
        - peOAuth:
            - pricing:lease
      x-pe-scope: pricing:lease
      x-pe-rate-limit-bucket: pricing
  /pricing/sungage/products:
    get:
      operationId: listSungageProducts
      tags:
        - Sungage pricing
      summary: List Sungage products
      description: |-
        List the Sungage Prepaid TPO products, terms and rates for a state. Needs X-PE-Actor-Email.

        **Scope:** `pricing:sungage`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`ACTOR_REQUIRED`](#error-ACTOR_REQUIRED) | 400 | no |
        | [`VALIDATION_FAILED`](#error-VALIDATION_FAILED) | 400 | no |
        | [`UNKNOWN_FIELD`](#error-UNKNOWN_FIELD) | 400 | no |
        | [`SUNGAGE_NOT_ENROLLED`](#error-SUNGAGE_NOT_ENROLLED) | 403 | no |
        | [`SUNGAGE_USER_NOT_REGISTERED`](#error-SUNGAGE_USER_NOT_REGISTERED) | 403 | no |
        | [`SUNGAGE_UNAVAILABLE`](#error-SUNGAGE_UNAVAILABLE) | 503 | yes |
        | [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: stateCode
          in: query
          required: true
          schema:
            type: string
            pattern: ^[A-Za-z]{2}$
          example: CA
      responses:
        "200":
          description: The products.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SungageProductsResponse"
              examples:
                products:
                  summary: California products
                  value:
                    data:
                      stateCode: CA
                      environment: sandbox
                      isPrepaidTpoState: true
                      products:
                        - dppProduct: Classic DPP
                          terms:
                            - term: 10
                              options:
                                - rate: 2.99
                                  isDefault: false
                                - rate: 3.99
                                  isDefault: true
                            - term: 20
                              options:
                                - rate: 3.99
                                  isDefault: true
                                - rate: 4.99
                                  isDefault: false
                        - dppProduct: Escalator
                          terms:
                            - term: 25
                              options:
                                - rate: 1.99
                                  isDefault: true
                                  escalatorPercentage: 2.9
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD, ACTOR_REQUIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, SUNGAGE_NOT_ENROLLED, SUNGAGE_USER_NOT_REGISTERED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                SUNGAGE_NOT_ENROLLED:
                  $ref: "#/components/examples/Error_SUNGAGE_NOT_ENROLLED"
                SUNGAGE_USER_NOT_REGISTERED:
                  $ref: "#/components/examples/Error_SUNGAGE_USER_NOT_REGISTERED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: STATE_NOT_SUPPORTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED, SUNGAGE_UNAVAILABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
                SUNGAGE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SUNGAGE_UNAVAILABLE"
      security:
        - bearerAuth: []
        - peOAuth:
            - pricing:sungage
      x-pe-scope: pricing:sungage
      x-pe-rate-limit-bucket: pricing
  /pricing/sungage:
    post:
      operationId: priceSungage
      tags:
        - Sungage pricing
      summary: Price a PE lease with a Sungage loan
      description: |-
        Price a PE lease with a Sungage loan. Send the lease inputs and one product, term and rate from GET /pricing/sungage/products. Needs X-PE-Actor-Email. The quote never creates a project.

        **Scope:** `pricing:sungage`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`ACTOR_REQUIRED`](#error-ACTOR_REQUIRED) | 400 | no |
        | [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US) | 422 | no |
        | [`EPC_OUT_OF_RANGE`](#error-EPC_OUT_OF_RANGE) | 422 | no |
        | [`ROOFING_COST_INVALID`](#error-ROOFING_COST_INVALID) | 422 | no |
        | [`INCENTIVE_NOT_AVAILABLE`](#error-INCENTIVE_NOT_AVAILABLE) | 422 | no |
        | [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED) | 422 | no |
        | [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND) | 404 | no |
        | [`SAFE_HARBOR_UNITS_INVALID`](#error-SAFE_HARBOR_UNITS_INVALID) | 422 | no |
        | [`STATE_MISMATCH`](#error-STATE_MISMATCH) | 422 | no |
        | [`SALES_TAX_UNRESOLVED`](#error-SALES_TAX_UNRESOLVED) | 422 | no |
        | [`TAX_RATE_UNAVAILABLE`](#error-TAX_RATE_UNAVAILABLE) | 503 | yes |
        | [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND) | 422 | no |
        | [`EC_LOOKUP_UNAVAILABLE`](#error-EC_LOOKUP_UNAVAILABLE) | 503 | yes |
        | [`SUNGAGE_NOT_ENROLLED`](#error-SUNGAGE_NOT_ENROLLED) | 403 | no |
        | [`SUNGAGE_USER_NOT_REGISTERED`](#error-SUNGAGE_USER_NOT_REGISTERED) | 403 | no |
        | [`SUNGAGE_PRODUCT_UNAVAILABLE`](#error-SUNGAGE_PRODUCT_UNAVAILABLE) | 422 | no |
        | [`SUNGAGE_UNAVAILABLE`](#error-SUNGAGE_UNAVAILABLE) | 503 | yes |
        | [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX) | 422 | no |
        | [`EPC_PER_WATT_OUT_OF_RANGE`](#error-EPC_PER_WATT_OUT_OF_RANGE) | 422 | no |
        | [`SYSTEM_SIZE_LOOKS_LIKE_WATTS`](#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS) | 422 | no |
        | [`SYSTEM_SIZE_OUT_OF_RANGE`](#error-SYSTEM_SIZE_OUT_OF_RANGE) | 422 | no |
        | [`CONTRACT_DATE_OUT_OF_RANGE`](#error-CONTRACT_DATE_OUT_OF_RANGE) | 422 | no |
        | [`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`](#error-CONTRACT_DATE_BEFORE_RETITC_CUTOFF) | 422 | no |
        | [`INCENTIVE_OUT_OF_RANGE`](#error-INCENTIVE_OUT_OF_RANGE) | 422 | no |
        | [`ROOFING_COST_NOT_APPLICABLE`](#error-ROOFING_COST_NOT_APPLICABLE) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SungagePriceRequest"
            examples:
              classic:
                summary: Classic DPP, 20 years
                value:
                  epcAmount: 36500
                  systemType: solar_only
                  insuranceOption: 1
                  address:
                    street: 250 Sample Avenue
                    city: Fresno
                    stateCode: CA
                    zipCode: "93721"
                  pvDomesticContent: true
                  storageDomesticContent: false
                  energyCommunity: false
                  dcBonusRecipient: customer
                  contractDate: "2026-11-10"
                  dppProduct: Classic DPP
                  term: 20
                  rate: 3.99
      responses:
        "200":
          description: The quote.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SungageQuoteResponse"
              examples:
                quote:
                  summary: A Test quote
                  value:
                    data:
                      quoteId: qte_6Gd2Hs8Kf3Lj7Qw9Er1T
                      environment: sandbox
                      sungage:
                        stateCode: CA
                        dppProduct: Classic DPP
                        term: 20
                        rate: 3.99
                      loan:
                        epcAmount: 36500
                        insuranceRate: 0
                        insuranceAmount: 0
                        eligibleRoofCost: 0
                        adjustedEpc: 40884.91
                        leaseFactor: 1.5384615
                        leaseDiscountPercent: 35
                        leaseDiscount: 14309.72
                        ineligibleRoofFinanced: 0
                        customerNad: 26575.19
                        salesTaxRate: 0
                        salesTaxAmount: 0
                        loanAmount: 26575.19
                        estimatedMonthlyPayment: 160.9
                        escalatorPercentage: null
                        paymentsNote: null
                      installerPayments:
                        sungageFundsInstaller: 22190.28
                        leaseDiscount: 14309.72
                        dcBonusAmount: 0
                        pePayoutGross: 14309.72
                        safeHarborDeduction: 0
                        payoutBase: 14309.72
                        paymentAtICGross: 9539.81
                        salesTaxAmount: 0
                        insuranceAmount: 0
                        paymentAtIC: 9539.81
                        paymentAtPC: 4769.91
                      installerTotals:
                        installerFromSungage: 22190.28
                        installerFromPe: 14309.72
                        installerTotal: 36500
                      pricingChecksPassed: true
                      warnings: []
                      lease:
                        quoteId: qte_6Gd2Hs8Kf3Lj7Qw9Er1T
                        leaseFactor: 1.5384615
                        leaseDiscountPercent: 35
                        tierLeaseFactor: 1.5384615
                        insuranceRiskAdjustment: 0
                        adjustedEpc: 36500
                        replacementCost: 36500
                        leaseDiscount: 12775
                        netAmountDue: 23725
                        leaseAmount: 23725
                        salesTax:
                          rate: 0
                          amount: 0
                          taxable: false
                          source: STC
                          needsAttention: null
                        insuranceRiderAmount: 0
                        dcBonusAmount: 0
                        safeHarborDeduction: 0
                        pePayout: 12775
                        icPaymentGross: 8516.67
                        icPayment: 8516.67
                        pcPayment: 4258.33
                        inputsEcho:
                          epcAmount: 36500
                          eligibleRoofingCost: 0
                          ineligibleRoofingCost: 0
                          systemType: solar_only
                          insuranceOption: 1
                          address:
                            city: Fresno
                            stateCode: CA
                            zipCode: "93721"
                          taxStateCode: CA
                          pvDomesticContent: true
                          storageDomesticContent: false
                          energyCommunity: false
                          energyCommunitySource: request
                          energyCommunityCategory: null
                          dcBonusRecipient: customer
                          includedIncentive:
                            type: none
                            amount: 0
                          safeHarbor: null
                          existingSolarOnProperty: false
                          contractDate: "2026-11-10"
                        notes:
                          - "Lease discount: 35% of the Adjusted EPC ($36,500.00) is $12,775.00. The customer pays the replacement cost less this discount."
                          - The Domestic Content bonus goes to the customer as a larger lease discount.
                          - No lease sales tax applies at this address for this system type.
                          - PE pays the installer $8,516.67 at Inspection Complete (2/3 of the payout after Safe Harbor, less any deductions) and $4,258.33 at Project Complete (1/3).
                        warnings: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD, ACTOR_REQUIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, SUNGAGE_NOT_ENROLLED, SUNGAGE_USER_NOT_REGISTERED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                SUNGAGE_NOT_ENROLLED:
                  $ref: "#/components/examples/Error_SUNGAGE_NOT_ENROLLED"
                SUNGAGE_USER_NOT_REGISTERED:
                  $ref: "#/components/examples/Error_SUNGAGE_USER_NOT_REGISTERED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, SAFE_HARBOR_OPPORTUNITY_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: ADDRESS_OUTSIDE_US, EPC_OUT_OF_RANGE, ROOFING_COST_INVALID, INCENTIVE_NOT_AVAILABLE, STATE_NOT_SUPPORTED, SAFE_HARBOR_UNITS_INVALID, STATE_MISMATCH, SALES_TAX_UNRESOLVED, ADDRESS_NOT_FOUND, SUNGAGE_PRODUCT_UNAVAILABLE, ADDRESS_PO_BOX, EPC_PER_WATT_OUT_OF_RANGE, SYSTEM_SIZE_LOOKS_LIKE_WATTS, SYSTEM_SIZE_OUT_OF_RANGE, CONTRACT_DATE_OUT_OF_RANGE, CONTRACT_DATE_BEFORE_RETITC_CUTOFF, INCENTIVE_OUT_OF_RANGE, ROOFING_COST_NOT_APPLICABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ADDRESS_OUTSIDE_US:
                  $ref: "#/components/examples/Error_ADDRESS_OUTSIDE_US"
                EPC_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EPC_OUT_OF_RANGE"
                ROOFING_COST_INVALID:
                  $ref: "#/components/examples/Error_ROOFING_COST_INVALID"
                INCENTIVE_NOT_AVAILABLE:
                  $ref: "#/components/examples/Error_INCENTIVE_NOT_AVAILABLE"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
                SAFE_HARBOR_UNITS_INVALID:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_UNITS_INVALID"
                STATE_MISMATCH:
                  $ref: "#/components/examples/Error_STATE_MISMATCH"
                SALES_TAX_UNRESOLVED:
                  $ref: "#/components/examples/Error_SALES_TAX_UNRESOLVED"
                ADDRESS_NOT_FOUND:
                  $ref: "#/components/examples/Error_ADDRESS_NOT_FOUND"
                SUNGAGE_PRODUCT_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SUNGAGE_PRODUCT_UNAVAILABLE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED, TAX_RATE_UNAVAILABLE, EC_LOOKUP_UNAVAILABLE, SUNGAGE_UNAVAILABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
                TAX_RATE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_TAX_RATE_UNAVAILABLE"
                EC_LOOKUP_UNAVAILABLE:
                  $ref: "#/components/examples/Error_EC_LOOKUP_UNAVAILABLE"
                SUNGAGE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SUNGAGE_UNAVAILABLE"
      security:
        - bearerAuth: []
        - peOAuth:
            - pricing:sungage
      x-pe-scope: pricing:sungage
      x-pe-rate-limit-bucket: pricing
  /contract-uploads:
    post:
      operationId: createContractUpload
      tags:
        - Contract uploads
      summary: Create a contract upload
      description: |-
        Create an upload and get a signed URL for the PDF. Needs X-PE-Actor-Email. PE checks the installer before it creates the upload. Then PUT the PDF to uploadUrl once, with EVERY header in uploadHeaders and no Authorization header. A missing or changed header makes the storage service refuse the file. See The upload flow.

        **Scope:** `projects:create`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`ACTOR_REQUIRED`](#error-ACTOR_REQUIRED) | 400 | no |
        | [`SANDBOX_FIELD_IN_LIVE`](#error-SANDBOX_FIELD_IN_LIVE) | 400 | no |
        | [`SANDBOX_SCENARIO_INVALID`](#error-SANDBOX_SCENARIO_INVALID) | 400 | no |
        | [`PRODUCT_NOT_SUPPORTED`](#error-PRODUCT_NOT_SUPPORTED) | 422 | no |
        | [`INSTALLER_NOT_ELIGIBLE`](#error-INSTALLER_NOT_ELIGIBLE) | 403 | no |
        | [`INSTALLER_ON_HOLD`](#error-INSTALLER_ON_HOLD) | 403 | no |
        | [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED) | 422 | no |
        | [`STATE_NOT_ACTIVE_FOR_INSTALLER`](#error-STATE_NOT_ACTIVE_FOR_INSTALLER) | 403 | no |
        | [`PRODUCT_NOT_ENABLED`](#error-PRODUCT_NOT_ENABLED) | 403 | no |
        | [`DUPLICATE_VENDOR_PROJECT_ID`](#error-DUPLICATE_VENDOR_PROJECT_ID) | 409 | no |
        | [`DAILY_QUOTA_EXCEEDED`](#error-DAILY_QUOTA_EXCEEDED) | 429 | yes |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUploadRequest"
            examples:
              test:
                summary: A Test upload with a scenario
                value:
                  vendorProjectId: AUR-PRJ-104882
                  stateCode: TX
                  fileName: customer-agreement-signed.pdf
                  sizeBytes: 2483120
                  sandboxScenario: project_created_action_required
              live:
                summary: A production upload
                value:
                  vendorProjectId: AUR-PRJ-104882
                  stateCode: TX
                  productType: Synthetic Cash
                  fileName: customer-agreement-signed.pdf
                  sizeBytes: 2483120
      responses:
        "201":
          description: The upload exists. PUT the file to uploadUrl.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedUploadResponse"
              examples:
                created:
                  summary: Created
                  value:
                    data:
                      uploadId: upl_3Fh8Jk2Lm6Np9Qr4St7V
                      uploadUrl: https://storage.googleapis.com/pe-paddock-sandbox-central/design/aurora/grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y/upl_3Fh8Jk2Lm6Np9Qr4St7V.pdf?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=900&X-Goog-Signature=EXAMPLE
                      uploadMethod: PUT
                      uploadHeaders:
                        Content-Type: application/pdf
                        x-goog-if-generation-match: "0"
                        x-goog-content-length-range: 0,26214400
                      uploadExpiresAt: "2026-11-10T18:17:11.000Z"
                      status: awaiting_file
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD, ACTOR_REQUIRED, SANDBOX_FIELD_IN_LIVE, SANDBOX_SCENARIO_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                SANDBOX_FIELD_IN_LIVE:
                  $ref: "#/components/examples/Error_SANDBOX_FIELD_IN_LIVE"
                SANDBOX_SCENARIO_INVALID:
                  $ref: "#/components/examples/Error_SANDBOX_SCENARIO_INVALID"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, INSTALLER_NOT_ELIGIBLE, INSTALLER_ON_HOLD, STATE_NOT_ACTIVE_FOR_INSTALLER, PRODUCT_NOT_ENABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                INSTALLER_ON_HOLD:
                  $ref: "#/components/examples/Error_INSTALLER_ON_HOLD"
                STATE_NOT_ACTIVE_FOR_INSTALLER:
                  $ref: "#/components/examples/Error_STATE_NOT_ACTIVE_FOR_INSTALLER"
                PRODUCT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_PRODUCT_NOT_ENABLED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "409":
          description: "Conflict. Codes: DUPLICATE_VENDOR_PROJECT_ID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DUPLICATE_VENDOR_PROJECT_ID:
                  $ref: "#/components/examples/Error_DUPLICATE_VENDOR_PROJECT_ID"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: PRODUCT_NOT_SUPPORTED, STATE_NOT_SUPPORTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PRODUCT_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_PRODUCT_NOT_SUPPORTED"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED, DAILY_QUOTA_EXCEEDED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
                DAILY_QUOTA_EXCEEDED:
                  $ref: "#/components/examples/Error_DAILY_QUOTA_EXCEEDED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - projects:create
      x-pe-scope: projects:create
      x-pe-rate-limit-bucket: write
  /contract-uploads/{uploadId}/submit:
    post:
      operationId: submitContractUpload
      tags:
        - Contract uploads
      summary: Submit a contract upload
      description: |-
        Tell PE that the file is in place. PE checks the file and queues the review. Poll GET /contract-uploads/{uploadId} for the result.

        **Scope:** `projects:create`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND) | 404 | no |
        | [`UPLOAD_ALREADY_SUBMITTED`](#error-UPLOAD_ALREADY_SUBMITTED) | 409 | no |
        | [`UPLOAD_FILE_MISSING`](#error-UPLOAD_FILE_MISSING) | 422 | no |
        | [`UPLOAD_URL_EXPIRED`](#error-UPLOAD_URL_EXPIRED) | 410 | no |
        | [`UPLOAD_FILE_TOO_LARGE`](#error-UPLOAD_FILE_TOO_LARGE) | 413 | no |
        | [`UPLOAD_NOT_PDF`](#error-UPLOAD_NOT_PDF) | 422 | no |
        | [`UPLOAD_SIZE_MISMATCH`](#error-UPLOAD_SIZE_MISMATCH) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: uploadId
          in: path
          required: true
          description: The upload id.
          schema:
            type: string
          example: upl_3Fh8Jk2Lm6Np9Qr4St7V
      responses:
        "202":
          description: The review is queued.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmittedUploadResponse"
              examples:
                queued:
                  summary: Queued
                  value:
                    data:
                      uploadId: upl_3Fh8Jk2Lm6Np9Qr4St7V
                      status: queued
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict. Codes: UPLOAD_ALREADY_SUBMITTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPLOAD_ALREADY_SUBMITTED:
                  $ref: "#/components/examples/Error_UPLOAD_ALREADY_SUBMITTED"
        "410":
          description: "Gone. Codes: UPLOAD_URL_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPLOAD_URL_EXPIRED:
                  $ref: "#/components/examples/Error_UPLOAD_URL_EXPIRED"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE, UPLOAD_FILE_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
                UPLOAD_FILE_TOO_LARGE:
                  $ref: "#/components/examples/Error_UPLOAD_FILE_TOO_LARGE"
        "422":
          description: "The request breaks a rule. Codes: UPLOAD_FILE_MISSING, UPLOAD_NOT_PDF, UPLOAD_SIZE_MISMATCH."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPLOAD_FILE_MISSING:
                  $ref: "#/components/examples/Error_UPLOAD_FILE_MISSING"
                UPLOAD_NOT_PDF:
                  $ref: "#/components/examples/Error_UPLOAD_NOT_PDF"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - projects:create
      x-pe-scope: projects:create
      x-pe-rate-limit-bucket: write
  /contract-uploads/{uploadId}:
    get:
      operationId: getContractUpload
      tags:
        - Contract uploads
      summary: Read a contract upload
      description: |-
        Read the status and the outcome of an upload. Poll with backoff until status is completed or failed.

        **Scope:** `projects:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND) | 404 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: uploadId
          in: path
          required: true
          description: The upload id.
          schema:
            type: string
          example: upl_3Fh8Jk2Lm6Np9Qr4St7V
      responses:
        "200":
          description: The upload.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResponse"
              examples:
                processing:
                  summary: Processing
                  value:
                    data:
                      uploadId: upl_3Fh8Jk2Lm6Np9Qr4St7V
                      vendorProjectId: AUR-PRJ-104882
                      status: processing
                      submittedAt: "2026-11-10T18:03:02.000Z"
                      completedAt: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
                created:
                  summary: Project created
                  value:
                    data:
                      uploadId: upl_3Fh8Jk2Lm6Np9Qr4St7V
                      vendorProjectId: AUR-PRJ-104882
                      status: completed
                      outcome: project_created
                      outcomeMessage: Participate Energy read the contract and created the project.
                      nextStep: Read the project with GET /v2/design/projects/{projectId} and follow its Actions and IC and PC approval status.
                      project:
                        projectId: SBX-TX2611-CUST4821
                        status: Active
                        milestone: Project Onboarded
                        documentReviewStatus: Under Review (PE)
                      submittedAt: "2026-11-10T18:03:02.000Z"
                      completedAt: "2026-11-10T18:03:22.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
                expired:
                  summary: Expired
                  value:
                    data:
                      uploadId: upl_3Fh8Jk2Lm6Np9Qr4St7V
                      vendorProjectId: AUR-PRJ-104882
                      status: expired
                      outcomeMessage: The upload URL expired before a file arrived, so this upload was closed and its vendorProjectId was released.
                      nextStep: Use the newer upload for this vendorProjectId, or create a new upload with POST /v2/design/contract-uploads.
                      submittedAt: null
                      completedAt: "2026-11-10T18:40:05.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
                draft:
                  summary: "Draft: failed basic tests"
                  value:
                    data:
                      uploadId: upl_3Fh8Jk2Lm6Np9Qr4St7V
                      vendorProjectId: AUR-PRJ-104882
                      status: completed
                      outcome: draft_failed_basic_tests
                      outcomeMessage: 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.
                      nextStep: 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.
                      checks:
                        - checkId: customer_signature_present
                          status: fail
                          message: The customer signature is missing on the signature page of the Customer Agreement (Customer 1). Upload a copy signed by every customer named on page 1.
                        - checkId: epc_amount_matches
                          status: fail
                          message: The EPC amount on the Installation Order does not match the EPC amount in the Customer Agreement pricing schedule. Correct the documents so both show the same amount.
                        - checkId: customer_initials_present
                          status: warn
                          message: The customer initials are missing in Section 9 (Arbitration). PE may ask for a copy with every initial box completed.
                      submittedAt: "2026-11-10T18:03:02.000Z"
                      completedAt: "2026-11-10T18:03:22.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
  /projects/by-vendor-id/{vendorProjectId}:
    get:
      operationId: getProjectByVendorId
      tags:
        - Projects
      summary: Read a project by your id
      description: |-
        Read the status of a project by your vendorProjectId.

        **Scope:** `projects:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND) | 404 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: vendorProjectId
          in: path
          required: true
          description: Your id for the project.
          schema:
            type: string
            pattern: ^[A-Za-z0-9_.:-]{1,128}$
          example: AUR-PRJ-104882
      responses:
        "200":
          description: The project status.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectStatusResponse"
              examples:
                project:
                  summary: IC review needs the installer
                  value:
                    data:
                      projectId: TX2611-SAMP4
                      vendorProjectId: AUR-PRJ-104882
                      environment: live
                      installer:
                        name: Sunbright Solar (example)
                      status: Active
                      milestone: Inspection Complete
                      documentReviewStatus: Action Required (Installer)
                      actionsRequired:
                        - title: Final permit sign-off missing
                          detail: The final permit does not show the inspector's sign-off. Upload the signed final permit from the authority having jurisdiction.
                          document: Signed Final Permit
                          createdAt: "2026-11-09T21:14:03.000Z"
                      icApproval:
                        status: action_required
                        date: null
                      pcApproval:
                        status: not_started
                        date: null
                      createdAt: "2026-11-02T16:40:12.000Z"
                      updatedAt: "2026-11-09T21:14:03.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
  /projects/{projectId}:
    get:
      operationId: getProject
      tags:
        - Projects
      summary: Read a project
      description: |-
        Read the status of a project by its PE Project ID.

        **Scope:** `projects:read`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND) | 404 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID.
          schema:
            type: string
          example: TX2611-SAMP4
      responses:
        "200":
          description: The project status.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectStatusResponse"
              examples:
                project:
                  summary: IC review needs the installer
                  value:
                    data:
                      projectId: TX2611-SAMP4
                      vendorProjectId: AUR-PRJ-104882
                      environment: live
                      installer:
                        name: Sunbright Solar (example)
                      status: Active
                      milestone: Inspection Complete
                      documentReviewStatus: Action Required (Installer)
                      actionsRequired:
                        - title: Final permit sign-off missing
                          detail: The final permit does not show the inspector's sign-off. Upload the signed final permit from the authority having jurisdiction.
                          document: Signed Final Permit
                          createdAt: "2026-11-09T21:14:03.000Z"
                      icApproval:
                        status: action_required
                        date: null
                      pcApproval:
                        status: not_started
                        date: null
                      createdAt: "2026-11-02T16:40:12.000Z"
                      updatedAt: "2026-11-09T21:14:03.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-10T18:02:11.482Z"
                approved:
                  summary: IC approved
                  value:
                    data:
                      projectId: TX2611-SAMP4
                      vendorProjectId: AUR-PRJ-104882
                      environment: live
                      installer:
                        name: Sunbright Solar (example)
                      status: Active
                      milestone: Inspection Complete
                      documentReviewStatus: Approved
                      actionsRequired: []
                      icApproval:
                        status: approved
                        date: "2026-11-10"
                      pcApproval:
                        status: not_started
                        date: null
                      createdAt: "2026-11-02T16:40:12.000Z"
                      updatedAt: "2026-11-09T21:14:03.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
  /webhooks:
    put:
      operationId: setWebhook
      tags:
        - Webhooks
      summary: Set the webhook URL
      description: |-
        Set the webhook URL for the environment of your token. The response has the signing secret.

        **Scope:** `webhooks:manage`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`WEBHOOK_URL_INVALID`](#error-WEBHOOK_URL_INVALID) | 400 | no |
        | [`WEBHOOK_URL_NOT_HTTPS`](#error-WEBHOOK_URL_NOT_HTTPS) | 400 | no |
        | [`WEBHOOK_URL_PRIVATE_ADDRESS`](#error-WEBHOOK_URL_PRIVATE_ADDRESS) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetWebhookRequest"
            examples:
              url:
                summary: A webhook URL
                value:
                  url: https://hooks.example-design.com/pe/webhooks
      responses:
        "200":
          description: The URL is set.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookWithSecretResponse"
              examples:
                set:
                  summary: Set
                  value:
                    data:
                      url: https://hooks.example-design.com/pe/webhooks
                      signingSecret: whsec_Jx2Wq8Lr5Tn3Vb7Mz1Kc9Hd4Ps6Fg0Ya2Ue8Io5Rt3
                      events:
                        - project.ic_approved
                        - project.pc_approved
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD, WEBHOOK_URL_INVALID, WEBHOOK_URL_NOT_HTTPS."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
                WEBHOOK_URL_INVALID:
                  $ref: "#/components/examples/Error_WEBHOOK_URL_INVALID"
                WEBHOOK_URL_NOT_HTTPS:
                  $ref: "#/components/examples/Error_WEBHOOK_URL_NOT_HTTPS"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "422":
          description: "The request breaks a rule. Codes: WEBHOOK_URL_PRIVATE_ADDRESS."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                WEBHOOK_URL_PRIVATE_ADDRESS:
                  $ref: "#/components/examples/Error_WEBHOOK_URL_PRIVATE_ADDRESS"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: write
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Read the webhook URL
      description: |-
        Read the webhook URL for the environment of your token. The signing secret is not returned.

        **Scope:** `webhooks:manage`

        **Errors** (and the common errors listed in Errors)

        This endpoint has no other error codes.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The URL.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
              examples:
                get:
                  summary: Set
                  value:
                    data:
                      url: https://hooks.example-design.com/pe/webhooks
                      events:
                        - project.ic_approved
                        - project.pc_approved
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: read
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete the webhook URL
      description: |-
        Remove the webhook URL for the environment of your token. Events that are due wait and retry on the normal schedule.

        **Scope:** `webhooks:manage`

        **Errors** (and the common errors listed in Errors)

        This endpoint has no other error codes.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The URL is removed.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeletedResponse"
              examples:
                deleted:
                  summary: Deleted
                  value:
                    data:
                      url: null
                      deleted: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: write
  /webhooks/rotate-secret:
    post:
      operationId: rotateWebhookSecret
      tags:
        - Webhooks
      summary: Rotate the signing secret
      description: |-
        Get a new signing secret for the environment of your token. The old secret stops working at once.

        **Scope:** `webhooks:manage`

        **Errors** (and the common errors listed in Errors)

        This endpoint has no other error codes.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The new secret.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookWithSecretResponse"
              examples:
                rotated:
                  summary: Rotated
                  value:
                    data:
                      url: https://hooks.example-design.com/pe/webhooks
                      signingSecret: whsec_Pq4Rt8Uv2Wx6Yz0Ab3Cd7Ef1Gh5Ij9Kl2Mn6Op0Qr4
                      events:
                        - project.ic_approved
                        - project.pc_approved
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: write
  /webhooks/test:
    post:
      operationId: testWebhook
      tags:
        - Webhooks
      summary: Send a test event
      description: |-
        Send one signed ping event to your URL now and return the result. PE does not retry a ping.

        **Scope:** `webhooks:manage`

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`WEBHOOK_NOT_CONFIGURED`](#error-WEBHOOK_NOT_CONFIGURED) | 422 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: The delivery result.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookTestResultResponse"
              examples:
                delivered:
                  summary: Delivered
                  value:
                    data:
                      delivered: true
                      statusCode: 200
                      durationMs: 184
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
                failed:
                  summary: Failed
                  value:
                    data:
                      delivered: false
                      statusCode: 500
                      durationMs: 312
                      error: HTTP 500
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "422":
          description: "The request breaks a rule. Codes: WEBHOOK_NOT_CONFIGURED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                WEBHOOK_NOT_CONFIGURED:
                  $ref: "#/components/examples/Error_WEBHOOK_NOT_CONFIGURED"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: write
  /sandbox/projects/{projectId}/simulate:
    post:
      operationId: simulateProjectEvent
      tags:
        - Sandbox
      summary: Simulate a project event
      description: |-
        Move a Test project to a new state. See the Sandbox section. Returns the new project status.

        **Scope:** `projects:read`. Test tokens only.

        **Errors** (and the common errors listed in Errors)

        | Code | HTTP | Retry |
        |---|---|---|
        | [`SANDBOX_ONLY`](#error-SANDBOX_ONLY) | 403 | no |
        | [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND) | 404 | no |
        | [`SANDBOX_TRANSITION_INVALID`](#error-SANDBOX_TRANSITION_INVALID) | 409 | no |
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: projectId
          in: path
          required: true
          description: A Test PE Project ID (SBX-...).
          schema:
            type: string
          example: SBX-TX2611-CUST4821
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SimulateRequest"
            examples:
              ic:
                summary: Approve IC
                value:
                  event: ic_approved
      responses:
        "200":
          description: The new project status.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectStatusResponse"
              examples:
                ic:
                  summary: IC approved
                  value:
                    data:
                      projectId: SBX-TX2611-CUST4821
                      vendorProjectId: AUR-PRJ-104882
                      environment: test
                      installer:
                        name: Sunbright Solar (example)
                      status: Active
                      milestone: Inspection Complete
                      documentReviewStatus: Approved
                      actionsRequired: []
                      icApproval:
                        status: approved
                        date: "2026-11-10"
                      pcApproval:
                        status: not_started
                        date: null
                      createdAt: "2026-11-02T16:40:12.000Z"
                      updatedAt: "2026-11-09T21:14:03.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-10T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, TOKEN_INVALID, TOKEN_EXPIRED, CLIENT_REVOKED, CLIENT_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AUTH_HEADER_MISSING:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MISSING"
                AUTH_HEADER_MALFORMED:
                  $ref: "#/components/examples/Error_AUTH_HEADER_MALFORMED"
                TOKEN_INVALID:
                  $ref: "#/components/examples/Error_TOKEN_INVALID"
                TOKEN_EXPIRED:
                  $ref: "#/components/examples/Error_TOKEN_EXPIRED"
                CLIENT_REVOKED:
                  $ref: "#/components/examples/Error_CLIENT_REVOKED"
                CLIENT_EXPIRED:
                  $ref: "#/components/examples/Error_CLIENT_EXPIRED"
        "403":
          description: "Access is not allowed. Codes: VENDOR_SUSPENDED, ENVIRONMENT_NOT_ENABLED, GRANT_REVOKED, INTEGRATION_NOT_ENABLED, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, SANDBOX_ONLY."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                VENDOR_SUSPENDED:
                  $ref: "#/components/examples/Error_VENDOR_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                GRANT_REVOKED:
                  $ref: "#/components/examples/Error_GRANT_REVOKED"
                INTEGRATION_NOT_ENABLED:
                  $ref: "#/components/examples/Error_INTEGRATION_NOT_ENABLED"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                SANDBOX_ONLY:
                  $ref: "#/components/examples/Error_SANDBOX_ONLY"
        "404":
          description: "Not found. Codes: GRANT_NOT_FOUND, RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                GRANT_NOT_FOUND:
                  $ref: "#/components/examples/Error_GRANT_NOT_FOUND"
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict. Codes: SANDBOX_TRANSITION_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SANDBOX_TRANSITION_INVALID:
                  $ref: "#/components/examples/Error_SANDBOX_TRANSITION_INVALID"
        "413":
          description: "Too large. Codes: BODY_TOO_LARGE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                BODY_TOO_LARGE:
                  $ref: "#/components/examples/Error_BODY_TOO_LARGE"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
        "500":
          description: "Unexpected error. Codes: INTERNAL_ERROR."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INTERNAL_ERROR:
                  $ref: "#/components/examples/Error_INTERNAL_ERROR"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SERVICE_DISABLED:
                  $ref: "#/components/examples/Error_SERVICE_DISABLED"
      security:
        - bearerAuth: []
        - peOAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: write
      x-pe-test-only: true
webhooks:
  project.ic_approved:
    post:
      operationId: webhookIcApproved
      summary: IC approved
      tags:
        - Webhooks
      description: PE approved the Inspection Complete milestone. Verify PE-Signature before you trust the body.
      parameters:
        - $ref: "#/components/parameters/PE-Webhook-Id"
        - $ref: "#/components/parameters/PE-Webhook-Timestamp"
        - $ref: "#/components/parameters/PE-Signature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApprovalEvent"
            examples:
              ic:
                summary: IC approved
                value:
                  id: evt_4f9c2b7e1a8d3c6b5e0f9a2d
                  type: project.ic_approved
                  createdAt: "2026-11-10T18:02:11.482Z"
                  environment: live
                  data:
                    projectId: TX2611-SAMP4
                    vendorProjectId: AUR-PRJ-104882
                    grantId: grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y
                    milestone: Inspection Complete
                    icApproval:
                      status: approved
                      date: "2026-11-10"
      responses:
        "200":
          description: Any 2xx status means delivered.
  project.pc_approved:
    post:
      operationId: webhookPcApproved
      summary: PC approved
      tags:
        - Webhooks
      description: PE approved the Project Complete milestone. Verify PE-Signature before you trust the body.
      parameters:
        - $ref: "#/components/parameters/PE-Webhook-Id"
        - $ref: "#/components/parameters/PE-Webhook-Timestamp"
        - $ref: "#/components/parameters/PE-Signature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApprovalEvent"
            examples:
              pc:
                summary: PC approved
                value:
                  id: evt_0b7d3e9a4c2f8b1e6d5a3c9f
                  type: project.pc_approved
                  createdAt: "2026-11-10T18:02:11.482Z"
                  environment: live
                  data:
                    projectId: TX2611-SAMP4
                    vendorProjectId: AUR-PRJ-104882
                    grantId: grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y
                    milestone: Project Complete
                    pcApproval:
                      status: approved
                      date: "2026-12-18"
      responses:
        "200":
          description: Any 2xx status means delivered.
  ping:
    post:
      operationId: webhookPing
      summary: Ping
      tags:
        - Webhooks
      description: Sent by POST /webhooks/test.
      parameters:
        - $ref: "#/components/parameters/PE-Webhook-Id"
        - $ref: "#/components/parameters/PE-Webhook-Timestamp"
        - $ref: "#/components/parameters/PE-Signature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PingEvent"
            examples:
              ping:
                summary: Ping
                value:
                  id: evt_7Qx2Lm9Rt4Vb8Nc3Kd6Hs1Fz
                  type: ping
                  createdAt: "2026-11-10T18:02:11.482Z"
                  environment: test
                  data: {}
      responses:
        "200":
          description: Any 2xx status means delivered.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The accessToken from POST /oauth/token. It lasts 60 minutes.
    clientBasic:
      type: http
      scheme: basic
      description: Your client ID and client secret, for POST /oauth/token and POST /connections/exchange only. You can send them in the body instead.
    peOAuth:
      type: oauth2
      description: "OAuth 2.0 client credentials with one extra token request field, grantId (see x-pe-token-request-fields). The token response is in the PE envelope: read data.accessToken. Send the token as a bearer token."
      flows:
        clientCredentials:
          tokenUrl: https://api.participate.energy/v2/design/oauth/token
          scopes:
            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.
      x-pe-token-request-fields:
        grantId:
          required: true
          description: The grant from POST /connections/exchange. The OAuth form name grant_id also works.
          pattern: ^grt_[0-9A-Za-z]{20}$
  headers:
    X-Request-Id:
      description: The request id. It is your X-Request-Id when you sent a valid one, else a new req_ id. Quote it when you contact PE.
      schema:
        type: string
    Cache-Control:
      description: Always private, no-store.
      schema:
        type: string
        const: private, no-store
    Retry-After:
      description: Seconds to wait before you retry.
      schema:
        type: integer
  parameters:
    X-Request-Id:
      name: X-Request-Id
      in: header
      required: false
      description: Your own request id. PE uses it as the response request id.
      schema:
        type: string
        pattern: ^[A-Za-z0-9._-]{1,64}$
      example: aurora-7f3c2b91
    X-PE-Actor-Email:
      name: X-PE-Actor-Email
      in: header
      required: false
      description: The email of the installer's sales rep. Optional here. When you send it, PE checks it against the installer.
      schema:
        type: string
        format: email
      example: rep@sunbright-solar.example
    X-PE-Actor-Email-Required:
      name: X-PE-Actor-Email
      in: header
      required: true
      description: The email of the installer's sales rep. Required here. It must be an active user of the installer, or have one of the installer's allowed domains.
      schema:
        type: string
        format: email
      example: rep@sunbright-solar.example
    PE-Webhook-Id:
      name: PE-Webhook-Id
      in: header
      required: true
      description: The event id. It is the same on every retry.
      schema:
        type: string
    PE-Webhook-Timestamp:
      name: PE-Webhook-Timestamp
      in: header
      required: true
      description: The send time in Unix seconds.
      schema:
        type: string
    PE-Signature:
      name: PE-Signature
      in: header
      required: true
      description: t=<timestamp>,v1=<hex HMAC-SHA256 of timestamp.rawBody with your signing secret>.
      schema:
        type: string
  examples:
    Error_AUTH_HEADER_MISSING:
      summary: AUTH_HEADER_MISSING
      value:
        error:
          code: AUTH_HEADER_MISSING
          message: "The request has no Authorization header. Send \"Authorization: Bearer <accessToken>\" with a token from POST /v2/design/oauth/token."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-AUTH_HEADER_MISSING
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_AUTH_HEADER_MALFORMED:
      summary: AUTH_HEADER_MALFORMED
      value:
        error:
          code: AUTH_HEADER_MALFORMED
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-AUTH_HEADER_MALFORMED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_TOKEN_INVALID:
      summary: TOKEN_INVALID
      value:
        error:
          code: TOKEN_INVALID
          message: "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."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-TOKEN_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_TOKEN_EXPIRED:
      summary: TOKEN_EXPIRED
      value:
        error:
          code: TOKEN_EXPIRED
          message: The access token expired at 2026-11-10T17:58:00.000Z. Tokens last 60 minutes; get a new token from POST /v2/design/oauth/token and send the request again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-TOKEN_EXPIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_INVALID_CLIENT:
      summary: INVALID_CLIENT
      value:
        error:
          code: INVALID_CLIENT
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-INVALID_CLIENT
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_CLIENT_REVOKED:
      summary: CLIENT_REVOKED
      value:
        error:
          code: CLIENT_REVOKED
          message: The client credential dc_test_Q7mN2pR8sT4vX1yZ3aB5cD6e has been revoked. Use an active credential, or ask Participate Energy for a new one.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-CLIENT_REVOKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_CLIENT_EXPIRED:
      summary: CLIENT_EXPIRED
      value:
        error:
          code: CLIENT_EXPIRED
          message: The client credential dc_test_Q7mN2pR8sT4vX1yZ3aB5cD6e expired at 2026-11-01T00:00:00.000Z. Ask Participate Energy for a replacement credential.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-CLIENT_EXPIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_VENDOR_SUSPENDED:
      summary: VENDOR_SUSPENDED
      value:
        error:
          code: VENDOR_SUSPENDED
          message: Design API access for your company is suspended. Contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-VENDOR_SUSPENDED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_ENVIRONMENT_NOT_ENABLED:
      summary: ENVIRONMENT_NOT_ENABLED
      value:
        error:
          code: ENVIRONMENT_NOT_ENABLED
          message: The live environment is not enabled for your company. Use a credential for an enabled environment, or ask Participate Energy to enable it.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-ENVIRONMENT_NOT_ENABLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_GRANT_REVOKED:
      summary: GRANT_REVOKED
      value:
        error:
          code: GRANT_REVOKED
          message: The connection grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-GRANT_REVOKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_INTEGRATION_NOT_ENABLED:
      summary: INTEGRATION_NOT_ENABLED
      value:
        error:
          code: INTEGRATION_NOT_ENABLED
          message: This installer does not have your integration enabled. Ask the installer to contact Participate Energy to enable it.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-INTEGRATION_NOT_ENABLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SCOPE_NOT_GRANTED:
      summary: SCOPE_NOT_GRANTED
      value:
        error:
          code: SCOPE_NOT_GRANTED
          message: This endpoint needs the scope pricing:sungage, 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SCOPE_NOT_GRANTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_ACTOR_NOT_ON_ROSTER:
      summary: ACTOR_NOT_ON_ROSTER
      value:
        error:
          code: ACTOR_NOT_ON_ROSTER
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-ACTOR_NOT_ON_ROSTER
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_INSTALLER_NOT_ELIGIBLE:
      summary: INSTALLER_NOT_ELIGIBLE
      value:
        error:
          code: INSTALLER_NOT_ELIGIBLE
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-INSTALLER_NOT_ELIGIBLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_INSTALLER_ON_HOLD:
      summary: INSTALLER_ON_HOLD
      value:
        error:
          code: INSTALLER_ON_HOLD
          message: This installer cannot create new projects right now because its account is on hold. Ask the installer to contact Participate Energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-INSTALLER_ON_HOLD
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_STATE_NOT_ACTIVE_FOR_INSTALLER:
      summary: STATE_NOT_ACTIVE_FOR_INSTALLER
      value:
        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: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_PRODUCT_NOT_ENABLED:
      summary: PRODUCT_NOT_ENABLED
      value:
        error:
          code: PRODUCT_NOT_ENABLED
          message: The product Synthetic Cash is not enabled for this installer. Ask the installer to contact Participate Energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-PRODUCT_NOT_ENABLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SUNGAGE_NOT_ENROLLED:
      summary: SUNGAGE_NOT_ENROLLED
      value:
        error:
          code: SUNGAGE_NOT_ENROLLED
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SUNGAGE_NOT_ENROLLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SUNGAGE_USER_NOT_REGISTERED:
      summary: SUNGAGE_USER_NOT_REGISTERED
      value:
        error:
          code: SUNGAGE_USER_NOT_REGISTERED
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SUNGAGE_USER_NOT_REGISTERED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SANDBOX_ONLY:
      summary: SANDBOX_ONLY
      value:
        error:
          code: SANDBOX_ONLY
          message: This endpoint works only with Test environment tokens. Get a token with your Test credential to simulate project events.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SANDBOX_ONLY
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_RESOURCE_NOT_FOUND:
      summary: RESOURCE_NOT_FOUND
      value:
        error:
          code: RESOURCE_NOT_FOUND
          message: No project with this id is available to your integration for this installer in the test environment. Check the id, the installer connection and the environment of your token.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-RESOURCE_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_GRANT_NOT_FOUND:
      summary: GRANT_NOT_FOUND
      value:
        error:
          code: GRANT_NOT_FOUND
          message: The grant id grt_8Hn3Kq7Lw2Pz5Rv9Tx4Y does not name a connection for your company. Use the grantId returned by POST /v2/design/connections/exchange.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-GRANT_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
      summary: SAFE_HARBOR_OPPORTUNITY_NOT_FOUND
      value:
        error:
          code: SAFE_HARBOR_OPPORTUNITY_NOT_FOUND
          message: The Safe Harbor opportunity SHO-2025-D-0999 is not available to this installer. Use an opportunityId from GET /v2/design/safe-harbor/opportunities.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_CONNECTION_CODE_USED:
      summary: CONNECTION_CODE_USED
      value:
        error:
          code: CONNECTION_CODE_USED
          message: This connection code was already exchanged. A code works once; ask the installer to create a new one in the Installer Portal.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-CONNECTION_CODE_USED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_DUPLICATE_VENDOR_PROJECT_ID:
      summary: DUPLICATE_VENDOR_PROJECT_ID
      value:
        error:
          code: DUPLICATE_VENDOR_PROJECT_ID
          message: The vendorProjectId AUR-PRJ-104882 was already used for this installer in the test environment. Read that upload with the uploadId in details, or send a different vendorProjectId.
          retryable: false
          details:
            - field: vendorProjectId
              issue: Already used.
              uploadId: upl_3Fh8Jk2Lm6Np9Qr4St7V
              projectId: null
          docsUrl: https://api.participate.energy/docs/design/v2/#error-DUPLICATE_VENDOR_PROJECT_ID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_UPLOAD_ALREADY_SUBMITTED:
      summary: UPLOAD_ALREADY_SUBMITTED
      value:
        error:
          code: UPLOAD_ALREADY_SUBMITTED
          message: Upload upl_3Fh8Jk2Lm6Np9Qr4St7V was already submitted and is now processing. Poll GET /v2/design/contract-uploads/upl_3Fh8Jk2Lm6Np9Qr4St7V for the result instead of submitting again.
          retryable: false
          details:
            - field: ""
              issue: The upload was already submitted.
              status: processing
          docsUrl: https://api.participate.energy/docs/design/v2/#error-UPLOAD_ALREADY_SUBMITTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SANDBOX_TRANSITION_INVALID:
      summary: SANDBOX_TRANSITION_INVALID
      value:
        error:
          code: SANDBOX_TRANSITION_INVALID
          message: "The event pc_approved cannot be simulated on this project now: IC is not approved yet; simulate ic_approved first. Send an event that fits the project's current state."
          retryable: false
          details:
            - field: event
              issue: IC is not approved yet; simulate ic_approved first
              received: pc_approved
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SANDBOX_TRANSITION_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_CONNECTION_CODE_EXPIRED:
      summary: CONNECTION_CODE_EXPIRED
      value:
        error:
          code: CONNECTION_CODE_EXPIRED
          message: This connection code expired. Codes last 72 hours; ask the installer to create a new one in the Installer Portal.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-CONNECTION_CODE_EXPIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_CONNECTION_CODE_REVOKED:
      summary: CONNECTION_CODE_REVOKED
      value:
        error:
          code: CONNECTION_CODE_REVOKED
          message: The installer revoked this connection code. Ask the installer to create a new one in the Installer Portal.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-CONNECTION_CODE_REVOKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_UPLOAD_URL_EXPIRED:
      summary: UPLOAD_URL_EXPIRED
      value:
        error:
          code: UPLOAD_URL_EXPIRED
          message: The upload URL for upload upl_3Fh8Jk2Lm6Np9Qr4St7V expired before a file arrived. Create a new upload with POST /v2/design/contract-uploads; you can use the same vendorProjectId.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-UPLOAD_URL_EXPIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_UTILITY_LIST_BY_STATE_RETIRED:
      summary: UTILITY_LIST_BY_STATE_RETIRED
      value:
        error:
          code: UTILITY_LIST_BY_STATE_RETIRED
          message: Utilities are listed by ZIP code. Use GET /v2/design/utilities?zipCode={zipCode}.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-UTILITY_LIST_BY_STATE_RETIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_BODY_TOO_LARGE:
      summary: BODY_TOO_LARGE
      value:
        error:
          code: BODY_TOO_LARGE
          message: The request body is 1300000 bytes, more than the 1048576 bytes allowed. Send a smaller JSON body.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-BODY_TOO_LARGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_UPLOAD_FILE_TOO_LARGE:
      summary: UPLOAD_FILE_TOO_LARGE
      value:
        error:
          code: UPLOAD_FILE_TOO_LARGE
          message: The uploaded file is 31457280 bytes, more than the 26214400 bytes allowed. Create a new upload for a smaller PDF; you can use the same vendorProjectId.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-UPLOAD_FILE_TOO_LARGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_UNSUPPORTED_MEDIA_TYPE:
      summary: UNSUPPORTED_MEDIA_TYPE
      value:
        error:
          code: UNSUPPORTED_MEDIA_TYPE
          message: The request Content-Type is text/plain, but this endpoint accepts application/json. Send the body with that Content-Type.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-UNSUPPORTED_MEDIA_TYPE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_INVALID_JSON:
      summary: INVALID_JSON
      value:
        error:
          code: INVALID_JSON
          message: "The request body is not valid JSON. Send a JSON object with Content-Type: application/json."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-INVALID_JSON
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_VALIDATION_FAILED:
      summary: VALIDATION_FAILED
      value:
        error:
          code: VALIDATION_FAILED
          message: The request did not pass validation (2 problem(s)). Fix the fields listed in details and send the request again.
          retryable: false
          details:
            - field: address.zipCode
              issue: This value does not have the expected format.
              expected: regex
              received: string
            - field: insuranceOption
              issue: This value is not one of the allowed values.
              expected: 1 | 2 | 3
              received: 4
          docsUrl: https://api.participate.energy/docs/design/v2/#error-VALIDATION_FAILED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_UNKNOWN_FIELD:
      summary: UNKNOWN_FIELD
      value:
        error:
          code: UNKNOWN_FIELD
          message: The request has 1 field(s) this endpoint does not accept. Remove the fields listed in details and send the request again.
          retryable: false
          details:
            - field: customerName
              issue: This field is not accepted by this endpoint.
          docsUrl: https://api.participate.energy/docs/design/v2/#error-UNKNOWN_FIELD
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_CONNECTION_CODE_INVALID:
      summary: CONNECTION_CODE_INVALID
      value:
        error:
          code: CONNECTION_CODE_INVALID
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-CONNECTION_CODE_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_ACTOR_REQUIRED:
      summary: ACTOR_REQUIRED
      value:
        error:
          code: ACTOR_REQUIRED
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-ACTOR_REQUIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_ACTOR_INVALID_EMAIL:
      summary: ACTOR_INVALID_EMAIL
      value:
        error:
          code: ACTOR_INVALID_EMAIL
          message: The actor email is not a valid email address. Send one email address, for example rep@installer.com.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-ACTOR_INVALID_EMAIL
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SANDBOX_SCENARIO_INVALID:
      summary: SANDBOX_SCENARIO_INVALID
      value:
        error:
          code: SANDBOX_SCENARIO_INVALID
          message: "The sandboxScenario project_approved is not one of: project_created, project_created_action_required, draft_failed_basic_tests, draft_invalid_document, draft_duplicate, product_mismatch, canon_rejected, sibyl_error. Send one of the listed scenarios, or leave it out for project_created."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SANDBOX_SCENARIO_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SANDBOX_FIELD_IN_LIVE:
      summary: SANDBOX_FIELD_IN_LIVE
      value:
        error:
          code: SANDBOX_FIELD_IN_LIVE
          message: The field sandboxScenario works only in the Test environment. Remove it from live requests.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SANDBOX_FIELD_IN_LIVE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_WEBHOOK_URL_INVALID:
      summary: WEBHOOK_URL_INVALID
      value:
        error:
          code: WEBHOOK_URL_INVALID
          message: "The webhook URL is not usable: the URL has a user name or password. Send an absolute https URL with a public host name, no user name or password, at most 2048 characters."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-WEBHOOK_URL_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_WEBHOOK_URL_NOT_HTTPS:
      summary: WEBHOOK_URL_NOT_HTTPS
      value:
        error:
          code: WEBHOOK_URL_NOT_HTTPS
          message: The webhook URL must use https on port 443. Send an https URL without a custom port.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-WEBHOOK_URL_NOT_HTTPS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_CONNECTION_CODE_WRONG_VENDOR:
      summary: CONNECTION_CODE_WRONG_VENDOR
      value:
        error:
          code: CONNECTION_CODE_WRONG_VENDOR
          message: This connection code was created for a different vendor. Ask the installer to create a code for your company in the Installer Portal.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-CONNECTION_CODE_WRONG_VENDOR
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_NO_SCOPES_AVAILABLE:
      summary: NO_SCOPES_AVAILABLE
      value:
        error:
          code: NO_SCOPES_AVAILABLE
          message: 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.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-NO_SCOPES_AVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_ADDRESS_NOT_FOUND:
      summary: ADDRESS_NOT_FOUND
      value:
        error:
          code: ADDRESS_NOT_FOUND
          message: PE could not find this street address. Check the street number, street name, city and zipCode, and send the request again.
          retryable: false
          details:
            - field: address
              issue: Google did not match a precise street address. closestMatch is the place it matched.
              closestMatch: Example St, Austin, TX 78701, USA
          docsUrl: https://api.participate.energy/docs/design/v2/#error-ADDRESS_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_ADDRESS_OUTSIDE_US:
      summary: ADDRESS_OUTSIDE_US
      value:
        error:
          code: ADDRESS_OUTSIDE_US
          message: The address is not in the United States. Participate Energy works with US addresses only.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-ADDRESS_OUTSIDE_US
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_STATE_NOT_SUPPORTED:
      summary: STATE_NOT_SUPPORTED
      value:
        error:
          code: STATE_NOT_SUPPORTED
          message: Participate Energy does not operate in OH. Use a state from GET /v2/design/states.
          retryable: false
          details:
            - field: address.stateCode
              issue: Participate Energy does not operate in this state.
              received: OH
          docsUrl: https://api.participate.energy/docs/design/v2/#error-STATE_NOT_SUPPORTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_STATE_MISMATCH:
      summary: STATE_MISMATCH
      value:
        error:
          code: STATE_MISMATCH
          message: The site address or its ZIP code is in NV, but the request says CA. Send the stateCode and zipCode of the site address.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-STATE_MISMATCH
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_EQUIPMENT_NOT_ON_AVL:
      summary: EQUIPMENT_NOT_ON_AVL
      value:
        error:
          code: EQUIPMENT_NOT_ON_AVL
          message: The equipment XYZ-400W-EXAMPLE is not on the Participate Energy approved vendor list. Use a SKU from GET /v2/design/avl.
          retryable: false
          details:
            - field: equipment[0].sku
              issue: This SKU is not on the approved vendor list.
              code: EQUIPMENT_NOT_ON_AVL
              category: pv_module
          docsUrl: https://api.participate.energy/docs/design/v2/#error-EQUIPMENT_NOT_ON_AVL
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_EQUIPMENT_AMBIGUOUS:
      summary: EQUIPMENT_AMBIGUOUS
      value:
        error:
          code: EQUIPMENT_AMBIGUOUS
          message: The equipment IQ8 matches more than one item on the approved vendor list. Send the exact SKU from GET /v2/design/avl.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-EQUIPMENT_AMBIGUOUS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SAFE_HARBOR_UNITS_INVALID:
      summary: SAFE_HARBOR_UNITS_INVALID
      value:
        error:
          code: SAFE_HARBOR_UNITS_INVALID
          message: The Safe Harbor units (150) are not valid for this opportunity (120 available). Send a whole number from 1 to the available units.
          retryable: false
          details:
            - field: safeHarbor.units
              issue: Safe Harbor units must be a whole number from 1 to the units available on the opportunity.
              expected: integer from 1 to 120
              received: 150
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SAFE_HARBOR_UNITS_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_EPC_OUT_OF_RANGE:
      summary: EPC_OUT_OF_RANGE
      value:
        error:
          code: EPC_OUT_OF_RANGE
          message: The epcAmount is the total EPC in US dollars, between 1,000 and 500,000; 3.2 is outside that range. It looks like a $/W price or an amount in thousands; send the total EPC, for example 60000 for $60,000.
          retryable: false
          details:
            - field: epcAmount
              issue: epcAmount is the total EPC in US dollars, between 1,000 and 500,000. It looks like a $/W price or an amount in thousands; send the total EPC, for example 60000 for $60,000.
              expected: 1000 to 500000 (US dollars)
              received: 3.2
          docsUrl: https://api.participate.energy/docs/design/v2/#error-EPC_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_ROOFING_COST_INVALID:
      summary: ROOFING_COST_INVALID
      value:
        error:
          code: ROOFING_COST_INVALID
          message: "The roofing costs are not valid: a roofing cost is negative. Send amounts of 0 or more, in USD."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-ROOFING_COST_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_INCENTIVE_NOT_AVAILABLE:
      summary: INCENTIVE_NOT_AVAILABLE
      value:
        error:
          code: INCENTIVE_NOT_AVAILABLE
          message: The included incentive hawaii_retitc is not available for this installer or state. Send type "none", or an incentive that applies.
          retryable: false
          details:
            - field: includedIncentive.type
              issue: The Hawaii RETITC is an included incentive only for Hawaii contracts dated before 2026-07-03.
              expected: "\"none\""
              received: hawaii_retitc
          docsUrl: https://api.participate.energy/docs/design/v2/#error-INCENTIVE_NOT_AVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SALES_TAX_UNRESOLVED:
      summary: SALES_TAX_UNRESOLVED
      value:
        error:
          code: SALES_TAX_UNRESOLVED
          message: The sales tax rate for this address could not be found. Check the address, or contact Participate Energy if it is correct.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SALES_TAX_UNRESOLVED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SUNGAGE_PRODUCT_UNAVAILABLE:
      summary: SUNGAGE_PRODUCT_UNAVAILABLE
      value:
        error:
          code: SUNGAGE_PRODUCT_UNAVAILABLE
          message: The Sungage product, term or rate is not available for this installer and project. Use a combination from GET /v2/design/pricing/sungage/products.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SUNGAGE_PRODUCT_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_PRODUCT_NOT_SUPPORTED:
      summary: PRODUCT_NOT_SUPPORTED
      value:
        error:
          code: PRODUCT_NOT_SUPPORTED
          message: The productType Distributed Microgrid is not supported by the Design API v2. Send "Synthetic Cash" or leave it out.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-PRODUCT_NOT_SUPPORTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_UPLOAD_FILE_MISSING:
      summary: UPLOAD_FILE_MISSING
      value:
        error:
          code: UPLOAD_FILE_MISSING
          message: No file was found for upload upl_3Fh8Jk2Lm6Np9Qr4St7V. PUT the PDF to the uploadUrl first, then submit.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-UPLOAD_FILE_MISSING
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_UPLOAD_NOT_PDF:
      summary: UPLOAD_NOT_PDF
      value:
        error:
          code: UPLOAD_NOT_PDF
          message: The file for upload upl_3Fh8Jk2Lm6Np9Qr4St7V is not a PDF. Upload the signed contract as a PDF with a new upload; you can use the same vendorProjectId.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-UPLOAD_NOT_PDF
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_WEBHOOK_URL_PRIVATE_ADDRESS:
      summary: WEBHOOK_URL_PRIVATE_ADDRESS
      value:
        error:
          code: WEBHOOK_URL_PRIVATE_ADDRESS
          message: The webhook host hooks.internal.example resolves to a private, local or reserved address. Use a host that resolves to public internet addresses only.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-WEBHOOK_URL_PRIVATE_ADDRESS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_WEBHOOK_NOT_CONFIGURED:
      summary: WEBHOOK_NOT_CONFIGURED
      value:
        error:
          code: WEBHOOK_NOT_CONFIGURED
          message: No webhook URL is set for the test environment. Set one with PUT /v2/design/webhooks first.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-WEBHOOK_NOT_CONFIGURED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_RATE_LIMITED:
      summary: RATE_LIMITED
      value:
        error:
          code: RATE_LIMITED
          message: "Too many requests: the limit is 60 per minute. Wait for the Retry-After seconds, then retry."
          retryable: true
          details:
            - field: ""
              issue: Rate limit reached.
              limit: 60
              window: minute
              resetAt: "2026-11-10T18:03:00.000Z"
          docsUrl: https://api.participate.energy/docs/design/v2/#error-RATE_LIMITED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_DAILY_QUOTA_EXCEEDED:
      summary: DAILY_QUOTA_EXCEEDED
      value:
        error:
          code: DAILY_QUOTA_EXCEEDED
          message: This installer connection used its daily limit of 50 uploads in the test environment. The limit resets at 2026-11-11T00:00:00.000Z; retry after that.
          retryable: true
          details:
            - field: ""
              issue: Daily upload limit reached.
              limit: 50
              window: day
              resetAt: "2026-11-11T00:00:00.000Z"
          docsUrl: https://api.participate.energy/docs/design/v2/#error-DAILY_QUOTA_EXCEEDED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_EC_LOOKUP_UNAVAILABLE:
      summary: EC_LOOKUP_UNAVAILABLE
      value:
        error:
          code: EC_LOOKUP_UNAVAILABLE
          message: The Energy Community check is unavailable right now. Retry the same request in a few minutes, or send energyCommunity as true or false.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-EC_LOOKUP_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_TAX_RATE_UNAVAILABLE:
      summary: TAX_RATE_UNAVAILABLE
      value:
        error:
          code: TAX_RATE_UNAVAILABLE
          message: The sales tax service is unavailable right now. Retry the same request in a few minutes.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-TAX_RATE_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_ADDRESS_LOOKUP_UNAVAILABLE:
      summary: ADDRESS_LOOKUP_UNAVAILABLE
      value:
        error:
          code: ADDRESS_LOOKUP_UNAVAILABLE
          message: The address service is unavailable right now. Retry the same request in a few minutes.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-ADDRESS_LOOKUP_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SUNGAGE_UNAVAILABLE:
      summary: SUNGAGE_UNAVAILABLE
      value:
        error:
          code: SUNGAGE_UNAVAILABLE
          message: Sungage is unavailable right now. Retry the same request in a few minutes.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SUNGAGE_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_SERVICE_DISABLED:
      summary: SERVICE_DISABLED
      value:
        error:
          code: SERVICE_DISABLED
          message: The Design API is temporarily turned off by Participate Energy. Retry later; see raceway.support@participate.energy for status.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-SERVICE_DISABLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-10T18:02:11.482Z"
    Error_INTERNAL_ERROR:
      summary: INTERNAL_ERROR
      value:
        error:
          code: INTERNAL_ERROR
          message: An unexpected error occurred while handling request req_9Bv4Nc7Xz2Lk5Hj8Gf3D. Retry once; if it fails again, send the request id to raceway.support@participate.energy.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/design/v2/#error-INTERNAL_ERROR
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: test
          timestamp: "2026-11-10T18:02:11.482Z"
  schemas:
    Environment:
      type: string
      enum:
        - test
        - live
      description: The environment of the token. It comes from the client credential.
    Scope:
      type: string
      enum:
        - avl:read
        - eligibility:read
        - pricing:lease
        - pricing:sungage
        - projects:create
        - projects:read
        - webhooks:manage
      description: A Design API scope.
      x-enum-descriptions:
        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.
    ErrorCode:
      type: string
      enum:
        - AUTH_HEADER_MISSING
        - AUTH_HEADER_MALFORMED
        - TOKEN_INVALID
        - TOKEN_EXPIRED
        - INVALID_CLIENT
        - CLIENT_REVOKED
        - CLIENT_EXPIRED
        - VENDOR_SUSPENDED
        - ENVIRONMENT_NOT_ENABLED
        - GRANT_REVOKED
        - INTEGRATION_NOT_ENABLED
        - SCOPE_NOT_GRANTED
        - ACTOR_NOT_ON_ROSTER
        - INSTALLER_NOT_ELIGIBLE
        - INSTALLER_ON_HOLD
        - STATE_NOT_ACTIVE_FOR_INSTALLER
        - PRODUCT_NOT_ENABLED
        - SUNGAGE_NOT_ENROLLED
        - SUNGAGE_USER_NOT_REGISTERED
        - SANDBOX_ONLY
        - ROUTE_NOT_FOUND
        - RESOURCE_NOT_FOUND
        - GRANT_NOT_FOUND
        - SAFE_HARBOR_OPPORTUNITY_NOT_FOUND
        - METHOD_NOT_ALLOWED
        - CONNECTION_CODE_USED
        - DUPLICATE_VENDOR_PROJECT_ID
        - UPLOAD_ALREADY_SUBMITTED
        - SANDBOX_TRANSITION_INVALID
        - CONNECTION_CODE_EXPIRED
        - CONNECTION_CODE_REVOKED
        - UPLOAD_URL_EXPIRED
        - UTILITY_LIST_BY_STATE_RETIRED
        - BODY_TOO_LARGE
        - UPLOAD_FILE_TOO_LARGE
        - UNSUPPORTED_MEDIA_TYPE
        - INVALID_JSON
        - VALIDATION_FAILED
        - UNKNOWN_FIELD
        - CONNECTION_CODE_INVALID
        - ACTOR_REQUIRED
        - ACTOR_INVALID_EMAIL
        - SANDBOX_SCENARIO_INVALID
        - SANDBOX_FIELD_IN_LIVE
        - WEBHOOK_URL_INVALID
        - WEBHOOK_URL_NOT_HTTPS
        - CONNECTION_CODE_WRONG_VENDOR
        - NO_SCOPES_AVAILABLE
        - ADDRESS_NOT_FOUND
        - ADDRESS_AMBIGUOUS
        - ADDRESS_OUTSIDE_US
        - ADDRESS_PO_BOX
        - STATE_NOT_SUPPORTED
        - STATE_MISMATCH
        - UTILITY_NOT_FOUND
        - HOME_TYPE_NOT_ELIGIBLE
        - OWNERSHIP_NOT_ELIGIBLE
        - EXISTING_SOLAR_NOT_ELIGIBLE
        - EQUIPMENT_NOT_ON_AVL
        - EQUIPMENT_AMBIGUOUS
        - EQUIPMENT_CATEGORY_MISMATCH
        - EQUIPMENT_QUANTITY_OUT_OF_RANGE
        - SAFE_HARBOR_UNITS_INVALID
        - EPC_OUT_OF_RANGE
        - EPC_PER_WATT_OUT_OF_RANGE
        - SYSTEM_SIZE_LOOKS_LIKE_WATTS
        - SYSTEM_SIZE_OUT_OF_RANGE
        - CONTRACT_DATE_OUT_OF_RANGE
        - CONTRACT_DATE_BEFORE_RETITC_CUTOFF
        - AMOUNT_OUT_OF_RANGE
        - ROOFING_COST_INVALID
        - ROOFING_COST_NOT_APPLICABLE
        - INSURANCE_OPTION_INVALID
        - INCENTIVE_NOT_AVAILABLE
        - INCENTIVE_OUT_OF_RANGE
        - SALES_TAX_UNRESOLVED
        - SUNGAGE_PRODUCT_UNAVAILABLE
        - PRODUCT_NOT_SUPPORTED
        - UPLOAD_FILE_MISSING
        - UPLOAD_NOT_PDF
        - UPLOAD_SIZE_MISMATCH
        - WEBHOOK_URL_PRIVATE_ADDRESS
        - WEBHOOK_NOT_CONFIGURED
        - RATE_LIMITED
        - DAILY_QUOTA_EXCEEDED
        - EC_LOOKUP_UNAVAILABLE
        - TAX_RATE_UNAVAILABLE
        - ADDRESS_LOOKUP_UNAVAILABLE
        - SUNGAGE_UNAVAILABLE
        - UPSTREAM_TIMEOUT
        - SERVICE_DISABLED
        - INTERNAL_ERROR
      description: Every error code the Design API returns. See the Errors section for each code.
      x-enum-descriptions:
        AUTH_HEADER_MISSING: "The request has no Authorization header. Send \"Authorization: Bearer <accessToken>\" with a token from POST /v2/design/oauth/token."
        AUTH_HEADER_MALFORMED: 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.
        TOKEN_INVALID: "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."
        TOKEN_EXPIRED: 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.
        INVALID_CLIENT: 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.
        CLIENT_REVOKED: The client credential {clientId} has been revoked. Use an active credential, or ask Participate Energy for a new one.
        CLIENT_EXPIRED: The client credential {clientId} expired at {expiredAt}. Ask Participate Energy for a replacement credential.
        VENDOR_SUSPENDED: Design API access for your company is suspended. Contact Participate Energy at raceway.support@participate.energy.
        ENVIRONMENT_NOT_ENABLED: The {environment} environment is not enabled for your company. Use a credential for an enabled environment, or ask Participate Energy to enable it.
        GRANT_REVOKED: 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.
        INTEGRATION_NOT_ENABLED: This installer does not have your integration enabled. Ask the installer to contact Participate Energy to enable it.
        SCOPE_NOT_GRANTED: 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.
        ACTOR_NOT_ON_ROSTER: 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.
        INSTALLER_NOT_ELIGIBLE: 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.
        INSTALLER_ON_HOLD: This installer cannot create new projects right now because its account is on hold. Ask the installer to contact Participate Energy.
        STATE_NOT_ACTIVE_FOR_INSTALLER: 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.
        PRODUCT_NOT_ENABLED: The product {productType} is not enabled for this installer. Ask the installer to contact Participate Energy.
        SUNGAGE_NOT_ENROLLED: 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.
        SUNGAGE_USER_NOT_REGISTERED: 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.
        SANDBOX_ONLY: This endpoint works only with Test environment tokens. Get a token with your Test credential to simulate project events.
        ROUTE_NOT_FOUND: No Design API route matches {received}. Check the path against the API reference at https://api.participate.energy/docs/design/v2/.
        RESOURCE_NOT_FOUND: 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.
        GRANT_NOT_FOUND: The grant id {grantId} does not name a connection for your company. Use the grantId returned by POST /v2/design/connections/exchange.
        SAFE_HARBOR_OPPORTUNITY_NOT_FOUND: The Safe Harbor opportunity {opportunityId} is not available to this installer. Use an opportunityId from GET /v2/design/safe-harbor/opportunities.
        METHOD_NOT_ALLOWED: "The method {method} is not allowed on {path}. Allowed methods: {allowed}."
        CONNECTION_CODE_USED: This connection code was already exchanged. A code works once; ask the installer to create a new one in the Installer Portal.
        DUPLICATE_VENDOR_PROJECT_ID: 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.
        UPLOAD_ALREADY_SUBMITTED: Upload {uploadId} was already submitted and is now {status}. Poll GET /v2/design/contract-uploads/{uploadId} for the result instead of submitting again.
        SANDBOX_TRANSITION_INVALID: "The event {event} cannot be simulated on this project now: {reason}. Send an event that fits the project's current state."
        CONNECTION_CODE_EXPIRED: This connection code expired. Codes last 72 hours; ask the installer to create a new one in the Installer Portal.
        CONNECTION_CODE_REVOKED: The installer revoked this connection code. Ask the installer to create a new one in the Installer Portal.
        UPLOAD_URL_EXPIRED: 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.
        UTILITY_LIST_BY_STATE_RETIRED: Utilities are listed by ZIP code. Use GET /v2/design/utilities?zipCode={zipCode}.
        BODY_TOO_LARGE: The request body is {received} bytes, more than the {max} bytes allowed. Send a smaller JSON body.
        UPLOAD_FILE_TOO_LARGE: 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.
        UNSUPPORTED_MEDIA_TYPE: The request Content-Type is {received}, but this endpoint accepts {expected}. Send the body with that Content-Type.
        INVALID_JSON: "The request body is not valid JSON. Send a JSON object with Content-Type: application/json."
        VALIDATION_FAILED: The request did not pass validation ({count} problem(s)). Fix the fields listed in details and send the request again.
        UNKNOWN_FIELD: The request has {count} field(s) this endpoint does not accept. Remove the fields listed in details and send the request again.
        CONNECTION_CODE_INVALID: 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.
        ACTOR_REQUIRED: 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.
        ACTOR_INVALID_EMAIL: The actor email is not a valid email address. Send one email address, for example rep@installer.com.
        SANDBOX_SCENARIO_INVALID: "The sandboxScenario {received} is not one of: {allowed}. Send one of the listed scenarios, or leave it out for project_created."
        SANDBOX_FIELD_IN_LIVE: The field {field} works only in the Test environment. Remove it from live requests.
        WEBHOOK_URL_INVALID: "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."
        WEBHOOK_URL_NOT_HTTPS: The webhook URL must use https on port 443. Send an https URL without a custom port.
        CONNECTION_CODE_WRONG_VENDOR: This connection code was created for a different vendor. Ask the installer to create a code for your company in the Installer Portal.
        NO_SCOPES_AVAILABLE: 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.
        ADDRESS_NOT_FOUND: PE could not find this street address. Check the street number, street name, city and zipCode, and send the request again.
        ADDRESS_AMBIGUOUS: The address matches more than one place. Add the house number, unit or ZIP code so it matches one place.
        ADDRESS_OUTSIDE_US: The address is not in the United States. Participate Energy works with US addresses only.
        ADDRESS_PO_BOX: A site address cannot be a PO Box. Send the street address where the system is installed.
        STATE_NOT_SUPPORTED: Participate Energy does not operate in {stateCode}. Use a state from GET /v2/design/states.
        STATE_MISMATCH: The site address or its ZIP code is in {addressState}, but the request says {stateCode}. Send the stateCode and zipCode of the site address.
        UTILITY_NOT_FOUND: The utility is not on the list for {stateCode}. Use a name from GET /v2/design/utilities, sending the zipCode of the site address.
        HOME_TYPE_NOT_ELIGIBLE: Participate Energy does not lease systems on {homeType} homes. The customer does not qualify for a Participate Energy lease.
        OWNERSHIP_NOT_ELIGIBLE: The customer must own the home (fee simple ownership). A renter does not qualify for a Participate Energy lease.
        EXISTING_SOLAR_NOT_ELIGIBLE: 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.
        EQUIPMENT_NOT_ON_AVL: The equipment {sku} is not on the Participate Energy approved vendor list. Use a SKU from GET /v2/design/avl.
        EQUIPMENT_AMBIGUOUS: The equipment {sku} matches more than one item on the approved vendor list. Send the exact SKU from GET /v2/design/avl.
        EQUIPMENT_CATEGORY_MISMATCH: SKU {sku} is on the AVL as {avlCategory}; send category {avlCategory}.
        EQUIPMENT_QUANTITY_OUT_OF_RANGE: 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.
        SAFE_HARBOR_UNITS_INVALID: The Safe Harbor units ({received}) are not valid for this opportunity ({available} available). Send a whole number from 1 to the available units.
        EPC_OUT_OF_RANGE: The {field} is the total EPC in US dollars, between {min} and {max}; {received} is outside that range. {hint}.
        EPC_PER_WATT_OUT_OF_RANGE: 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.
        SYSTEM_SIZE_LOOKS_LIKE_WATTS: The {field} is in kW DC. {received} looks like watts; send {suggested}.
        SYSTEM_SIZE_OUT_OF_RANGE: System size is in kW DC, between {min} and {max}. The {field} {received} is outside that range.
        CONTRACT_DATE_OUT_OF_RANGE: 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.
        CONTRACT_DATE_BEFORE_RETITC_CUTOFF: 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.
        AMOUNT_OUT_OF_RANGE: The {field} is an amount in US dollars, between {min} and {max}; {received} is outside that range. {hint}.
        ROOFING_COST_INVALID: "The roofing costs are not valid: {reason}. Send amounts of 0 or more, in USD."
        ROOFING_COST_NOT_APPLICABLE: Roofing costs apply only to systems with solar. Send eligibleRoofingCost and ineligibleRoofingCost as 0, or leave them out, for a battery_only system.
        INSURANCE_OPTION_INVALID: The insuranceOption {received} is not available for this project. Send 1, 2 or 3.
        INCENTIVE_NOT_AVAILABLE: The included incentive {received} is not available for this installer or state. Send type "none", or an incentive that applies.
        INCENTIVE_OUT_OF_RANGE: 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.
        SALES_TAX_UNRESOLVED: The sales tax rate for this address could not be found. Check the address, or contact Participate Energy if it is correct.
        SUNGAGE_PRODUCT_UNAVAILABLE: The Sungage product, term or rate is not available for this installer and project. Use a combination from GET /v2/design/pricing/sungage/products.
        PRODUCT_NOT_SUPPORTED: The productType {received} is not supported by the Design API v2. Send "Synthetic Cash" or leave it out.
        UPLOAD_FILE_MISSING: No file was found for upload {uploadId}. PUT the PDF to the uploadUrl first, then submit.
        UPLOAD_NOT_PDF: 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.
        UPLOAD_SIZE_MISMATCH: 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.
        WEBHOOK_URL_PRIVATE_ADDRESS: The webhook host {host} resolves to a private, local or reserved address. Use a host that resolves to public internet addresses only.
        WEBHOOK_NOT_CONFIGURED: No webhook URL is set for the {environment} environment. Set one with PUT /v2/design/webhooks first.
        RATE_LIMITED: "Too many requests: the limit is {limit} {window}. Wait for the Retry-After seconds, then retry."
        DAILY_QUOTA_EXCEEDED: This installer connection used its daily limit of {limit} uploads in the {environment} environment. The limit resets at {resetAt}; retry after that.
        EC_LOOKUP_UNAVAILABLE: The Energy Community check is unavailable right now. Retry the same request in a few minutes, or send energyCommunity as true or false.
        TAX_RATE_UNAVAILABLE: The sales tax service is unavailable right now. Retry the same request in a few minutes.
        ADDRESS_LOOKUP_UNAVAILABLE: The address service is unavailable right now. Retry the same request in a few minutes.
        SUNGAGE_UNAVAILABLE: Sungage is unavailable right now. Retry the same request in a few minutes.
        UPSTREAM_TIMEOUT: A service this request depends on did not answer in time. Retry the same request in a few minutes.
        SERVICE_DISABLED: The Design API is temporarily turned off by Participate Energy. Retry later; see raceway.support@participate.energy for status.
        INTERNAL_ERROR: An unexpected error occurred while handling request {requestId}. Retry once; if it fails again, send the request id to raceway.support@participate.energy.
    UploadOutcome:
      type: string
      enum:
        - project_created
        - draft_failed_basic_tests
        - draft_invalid_document
        - draft_duplicate
        - draft_manual_entry
        - sibyl_error
        - canon_rejected
        - product_mismatch
        - cancelled
      description: The result of a contract upload.
      x-enum-descriptions:
        project_created: Participate Energy read the contract and created the project.
        draft_failed_basic_tests: 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.
        draft_invalid_document: The file does not look like a Participate Energy customer agreement, so no project was created.
        draft_duplicate: This contract matches a project that already exists for this installer, so it was saved as a draft and no new project was created.
        draft_manual_entry: The contract could not be read automatically, so it was saved as a draft for the installer to complete.
        sibyl_error: Participate Energy could not finish reading the contract because of a processing error. No project was created.
        canon_rejected: The contract was read, but its data did not pass Participate Energy's project checks, so no project was created.
        product_mismatch: The contract is for a different Participate Energy product than the one on the upload, so no project was created.
        cancelled: The upload was cancelled before a project was created.
    UploadStatus:
      type: string
      enum:
        - awaiting_file
        - queued
        - processing
        - completed
        - failed
        - expired
      description: The progress of a contract upload.
    SandboxScenario:
      type: string
      enum:
        - project_created
        - project_created_action_required
        - draft_failed_basic_tests
        - draft_invalid_document
        - draft_duplicate
        - product_mismatch
        - canon_rejected
        - sibyl_error
      description: "Test environment only: the simulated result of a contract upload."
      x-enum-descriptions:
        project_created: PE creates a Test project. Status `Active`, milestone `Project Onboarded`, review `Under Review (PE)`.
        project_created_action_required: PE creates a Test project with the review at `Action Required (Installer)` and two sample Actions.
        draft_failed_basic_tests: No project. The upload has sample failed checks (a missing signature and an EPC mismatch).
        draft_invalid_document: No project. The file does not read as a PE customer agreement.
        draft_duplicate: No project. The contract matches an existing project.
        product_mismatch: No project. The contract is for a different PE product.
        canon_rejected: No project. The contract data did not pass PE's project checks.
        sibyl_error: No project. The status is `failed`.
    SimulateEvent:
      type: string
      enum:
        - action_required
        - under_review
        - ic_approved
        - pc_approved
        - cancelled
      description: A simulated project event (Test environment only).
    PricingWarningCode:
      type: string
      enum:
        - STATE_NOT_ACTIVE_FOR_INSTALLER
        - SALES_TAX_NEEDS_ATTENTION
        - ENERGY_COMMUNITY_NOT_CONFIRMED
        - ENERGY_COMMUNITY_NOT_VERIFIED
        - FIELD_NOT_APPLICABLE
        - ROOFING_COST_HIGH
      description: A soft issue on a quote. The quote is still valid.
      x-enum-descriptions:
        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.
        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. field names it.
        ROOFING_COST_HIGH: A roofing cost is more than the EPC. Check that it is in US dollars and is the roofing cost only. The quote uses the amount as sent. field names it.
    PricingWarning:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          $ref: "#/components/schemas/PricingWarningCode"
        message:
          type: string
          description: A plain sentence to show to your user.
        field:
          type: string
          description: The request field the warning is about. Present on ENERGY_COMMUNITY_NOT_CONFIRMED, ENERGY_COMMUNITY_NOT_VERIFIED, FIELD_NOT_APPLICABLE and ROOFING_COST_HIGH.
    ApprovalStatus:
      type: string
      enum:
        - not_started
        - action_required
        - under_review
        - approved
      description: The status of an IC or PC approval. See the Projects section for the rules.
    Approval:
      type: object
      additionalProperties: false
      required:
        - status
        - date
      properties:
        status:
          $ref: "#/components/schemas/ApprovalStatus"
        date:
          type:
            - string
            - "null"
          description: The approval date (YYYY-MM-DD), or null.
          format: date
    Installer:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          description: The installer's name in PE's records.
    Meta:
      type: object
      additionalProperties: false
      required:
        - requestId
        - environment
        - timestamp
      properties:
        requestId:
          type: string
          description: The request id. It is also in the X-Request-Id header.
        environment:
          oneOf:
            - $ref: "#/components/schemas/Environment"
            - type: "null"
          description: The token environment, or null when PE could not authenticate the call.
        timestamp:
          type: string
          description: The response time (ISO 8601, UTC).
          format: date-time
    ErrorDetail:
      type: object
      additionalProperties: true
      required:
        - field
        - issue
      properties:
        field:
          type: string
          description: A dotted field path, for example address.zipCode. Empty for the whole request.
        issue:
          type: string
          description: What is wrong.
        expected:
          type: string
          description: What PE expected, when known.
        received:
          type:
            - string
            - number
            - boolean
            - "null"
          description: The type of the value you sent, or the value for numbers, booleans and enum values.
      description: One problem. Some codes add more fields, for example uploadId, limit or resetAt.
    Error:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - retryable
        - details
        - docsUrl
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        message:
          type: string
          description: "A full sentence: what happened and what to do."
        retryable:
          type: boolean
          description: True when the same request can succeed later.
        details:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetail"
        docsUrl:
          type: string
          description: A link to this code in the Errors section.
          format: uri
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
        - meta
      properties:
        error:
          $ref: "#/components/schemas/Error"
        meta:
          $ref: "#/components/schemas/Meta"
    Address:
      type: object
      additionalProperties: false
      required:
        - street
        - city
        - stateCode
        - zipCode
      properties:
        street:
          type: string
          description: The street line.
          minLength: 1
          maxLength: 200
        city:
          type: string
          minLength: 1
          maxLength: 100
        stateCode:
          type: string
          description: A 2-letter US state code.
          pattern: ^[A-Za-z]{2}$
        zipCode:
          type: string
          description: 5 digits, or ZIP+4. Not 00000.
          pattern: ^\d{5}(-\d{4})?$
      description: A US site address.
    TokenRequest:
      type: object
      additionalProperties: false
      required:
        - grantType
        - grantId
      properties:
        grantType:
          type: string
          const: client_credentials
        clientId:
          type: string
          description: Your client ID. Leave it out when you use HTTP Basic.
          pattern: ^dc_(test|live)_[0-9A-Za-z]{24}$
        clientSecret:
          type: string
          description: Your client secret. Leave it out when you use HTTP Basic.
          pattern: ^dcs_(test|live)_[0-9A-Za-z]{40}$
        grantId:
          type: string
          description: The grant from POST /connections/exchange.
          pattern: ^grt_[0-9A-Za-z]{20}$
    TokenFormRequest:
      type: object
      additionalProperties: false
      description: Form body. Use either the camelCase or the OAuth snake_case name of each field.
      properties:
        grant_type:
          type: string
          const: client_credentials
        grantType:
          type: string
          const: client_credentials
        client_id:
          type: string
        clientId:
          type: string
        client_secret:
          type: string
        clientSecret:
          type: string
        grant_id:
          type: string
        grantId:
          type: string
    Token:
      type: object
      additionalProperties: false
      required:
        - accessToken
        - tokenType
        - expiresIn
        - environment
        - scopes
        - grantId
        - installer
      properties:
        accessToken:
          type: string
          description: The bearer token.
        tokenType:
          type: string
          const: Bearer
        expiresIn:
          type: integer
          description: Seconds until the token expires.
          const: 3600
        environment:
          $ref: "#/components/schemas/Environment"
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
          description: "The scopes of the token: the scopes both the grant and your client credential allow."
        grantId:
          type: string
        installer:
          $ref: "#/components/schemas/Installer"
    ExchangeRequest:
      type: object
      additionalProperties: false
      required:
        - connectionCode
      properties:
        connectionCode:
          type: string
          description: The code from the installer.
          pattern: ^pec_[a-z2-7]{26}$
        clientId:
          type: string
          description: Your client ID. Leave it out when you use HTTP Basic.
        clientSecret:
          type: string
          description: Your client secret. Leave it out when you use HTTP Basic.
    Exchange:
      type: object
      additionalProperties: false
      required:
        - grantId
        - installer
        - scopes
        - createdAt
      properties:
        grantId:
          type: string
          description: Store it with the installer's record. It does not expire.
        installer:
          $ref: "#/components/schemas/Installer"
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
          description: The scopes the installer granted.
        createdAt:
          type: string
          format: date-time
    Grant:
      type: object
      additionalProperties: false
      required:
        - grantId
        - installer
        - scopes
        - environment
        - createdAt
        - status
      properties:
        grantId:
          type: string
        installer:
          $ref: "#/components/schemas/Installer"
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
          description: The scopes of your token.
        environment:
          $ref: "#/components/schemas/Environment"
        createdAt:
          type:
            - string
            - "null"
          format: date-time
        status:
          type: string
          enum:
            - active
            - revoked
    GrantRevoked:
      type: object
      additionalProperties: false
      required:
        - grantId
        - status
      properties:
        grantId:
          type: string
        status:
          type: string
          const: revoked
    Ping:
      type: object
      additionalProperties: false
      required:
        - ok
        - environment
        - vendor
        - installer
        - scopes
        - tokenExpiresAt
      properties:
        ok:
          type: boolean
          const: true
        environment:
          $ref: "#/components/schemas/Environment"
        vendor:
          type: string
          description: Your vendor code.
        installer:
          $ref: "#/components/schemas/Installer"
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
        tokenExpiresAt:
          type: string
          format: date-time
    AvlCategory:
      type: string
      enum:
        - bess
        - pv_module
        - pv_combo
        - pv_inverter
        - pv_racking
        - pv_railing
        - pv_fasteners
      description: An equipment category.
    DomesticContentValues:
      type: object
      additionalProperties:
        type: number
      description: Domestic Content values as PE stores them, as fractions (0.45 is 45%). Keys depend on the category, for example the module and inverter columns, or bessDC for batteries.
    AvlItem:
      type: object
      additionalProperties: false
      required:
        - sku
        - category
        - manufacturer
        - model
        - description
        - domesticContent
      properties:
        sku:
          type: string
        category:
          $ref: "#/components/schemas/AvlCategory"
        manufacturer:
          type: string
        model:
          type:
            - string
            - "null"
        description:
          type:
            - string
            - "null"
        domesticContent:
          $ref: "#/components/schemas/DomesticContentValues"
    AvlPage:
      type: object
      additionalProperties: false
      required:
        - avlVersionId
        - items
        - nextCursor
      properties:
        avlVersionId:
          type:
            - string
            - "null"
          description: The AVL version. Null when no version is active.
        items:
          type: array
          items:
            $ref: "#/components/schemas/AvlItem"
        nextCursor:
          type:
            - string
            - "null"
          description: Send it as cursor to get the next page. Null on the last page.
    SafeHarborOpportunity:
      type: object
      additionalProperties: false
      required:
        - opportunityId
        - name
        - unitCost
        - unitsAvailable
      properties:
        opportunityId:
          type: string
          description: The Safe Harbor opportunity id (SHOID).
        name:
          type: string
        unitCost:
          type: number
          description: The deduction for each unit. USD, rounded to cents.
        unitsAvailable:
          type:
            - integer
            - "null"
          description: Units left on the installer's allocation, or null when unknown.
    SafeHarborOpportunityList:
      type: object
      additionalProperties: false
      required:
        - opportunities
      properties:
        opportunities:
          type: array
          items:
            $ref: "#/components/schemas/SafeHarborOpportunity"
    CustomAvlItem:
      type: object
      additionalProperties: false
      required:
        - skuPattern
        - category
        - manufacturer
        - product
        - typeRef
        - domesticContent
      properties:
        skuPattern:
          type: string
          description: A SKU pattern that matches equipment.
        category:
          type: string
          description: pv_module, pv_inverter, pv_racking or bess.
        manufacturer:
          type: string
        product:
          type:
            - string
            - "null"
        typeRef:
          type:
            - string
            - "null"
        domesticContent:
          $ref: "#/components/schemas/DomesticContentValues"
    CustomAvlList:
      type: object
      additionalProperties: false
      required:
        - opportunityId
        - items
      properties:
        opportunityId:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/CustomAvlItem"
    StateList:
      type: object
      additionalProperties: false
      required:
        - states
        - enabledProducts
      properties:
        states:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - stateCode
              - name
            properties:
              stateCode:
                type: string
              name:
                type: string
        enabledProducts:
          type: array
          items:
            type: string
            enum:
              - Synthetic Cash
              - Distributed Microgrid
          description: The PE products enabled for the installer that you can upload with the Design API. Since 2.2 this lists only Synthetic Cash.
    UtilityList:
      type: object
      additionalProperties: false
      required:
        - zipCode
        - stateCode
        - utilities
      properties:
        zipCode:
          type: string
          description: The ZIP code you sent.
        stateCode:
          type:
            - string
            - "null"
          description: The 2-letter state of the ZIP code. It is null when PE does not know the ZIP code.
        utilities:
          type: array
          description: The utilities that serve the ZIP code. The primary utility is first.
          items:
            type: object
            additionalProperties: false
            required:
              - utilityId
              - name
              - primary
            properties:
              utilityId:
                type: string
              name:
                type: string
                description: Send this name as utility in POST /eligibility.
              primary:
                type: boolean
                description: True for the main utility of the ZIP code.
    EligibilityRequest:
      type: object
      additionalProperties: false
      required:
        - address
        - systemType
      properties:
        address:
          $ref: "#/components/schemas/Address"
        homeType:
          type: string
          enum:
            - single_family
            - townhome
            - condo
            - manufactured
            - multi_family
            - other
        ownership:
          type: string
          enum:
            - owner
            - renter
        existingSolarOnProperty:
          type: string
          enum:
            - none
            - add_to_existing
            - separate_system
        utility:
          type: string
          description: The utility name. See GET /utilities?zipCode=.
          minLength: 1
          maxLength: 200
        systemType:
          type: string
          enum:
            - solar_only
            - solar_battery
            - battery_only
    EligibilityCheck:
      type: object
      additionalProperties: false
      required:
        - check
        - result
        - message
      properties:
        check:
          type: string
          enum:
            - state
            - installer_state
            - product
            - utility
            - home_type
            - ownership
            - existing_solar
            - address
        result:
          type: string
          enum:
            - pass
            - fail
            - not_evaluated
        code:
          $ref: "#/components/schemas/ErrorCode"
        message:
          type: string
          description: A plain sentence to show to your user.
    Eligibility:
      type: object
      additionalProperties: false
      required:
        - eligible
        - stateCode
        - systemType
        - checks
      properties:
        eligible:
          type: boolean
          description: True when no check failed.
        stateCode:
          type: string
        systemType:
          type: string
          enum:
            - solar_only
            - solar_battery
            - battery_only
        checks:
          type: array
          items:
            $ref: "#/components/schemas/EligibilityCheck"
    DomesticContentRequest:
      type: object
      additionalProperties: false
      required:
        - equipment
      properties:
        equipment:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: object
            additionalProperties: false
            required:
              - sku
              - category
            properties:
              sku:
                type: string
                minLength: 1
                maxLength: 120
              category:
                $ref: "#/components/schemas/AvlCategory"
              quantity:
                type: integer
                description: The number of units. Default 1. A pv_module or pv_combo line takes at most 500 (EQUIPMENT_QUANTITY_OUT_OF_RANGE).
                default: 1
                minimum: 1
                maximum: 10000
        year:
          type: integer
          description: "The year for the Domestic Content and FEOC thresholds. Default: this year. A Safe Harbor beginning of construction date wins over it."
          minimum: 2025
          maximum: 2035
        safeHarborOpportunityId:
          type: string
          description: Include this opportunity's custom AVL.
    DcSummary:
      type: object
      additionalProperties: false
      required:
        - included
        - eligible
        - percent
        - threshold
      properties:
        included:
          type: boolean
          description: The request has equipment of this kind.
        eligible:
          type: boolean
          description: Domestic Content only. The FEOC result is in `feoc`.
        percent:
          type:
            - number
            - "null"
          description: The Domestic Content percent (45.5 is 45.5%), or null when not included or not computable.
        threshold:
          type: number
          description: The threshold percent.
        reason:
          type: string
          description: Why PE could not compute the percent. Present only then.
    DcItem:
      type: object
      additionalProperties: false
      required:
        - sku
        - category
        - resolved
        - source
      properties:
        sku:
          type: string
        category:
          $ref: "#/components/schemas/AvlCategory"
        quantity:
          type: integer
          description: The quantity sent, or 1 when you left it out (since 2.2).
        resolved:
          type: boolean
        source:
          type:
            - string
            - "null"
          enum:
            - avl
            - custom_avl
            - null
        manufacturer:
          type: string
        description:
          type:
            - string
            - "null"
        dcPercent:
          type:
            - number
            - "null"
          description: The item's Domestic Content percent, or null when PE could not compute it.
        feocPercent:
          type:
            - number
            - "null"
          description: The item's non-FEOC percent, or null when PE could not compute it.
        code:
          type: string
          enum:
            - EQUIPMENT_NOT_ON_AVL
            - EQUIPMENT_AMBIGUOUS
    FeocCategory:
      type: object
      additionalProperties: false
      required:
        - included
        - eligible
        - percent
        - threshold
      properties:
        included:
          type: boolean
          description: The request has equipment of this kind.
        eligible:
          type: boolean
          description: "true when the non-FEOC percent meets the threshold. Always true for an included kind when `applies` is false. false when the kind is not included or the percent is not computable."
        percent:
          type:
            - number
            - "null"
          description: The non-FEOC percent, that is the material assistance cost percent (45.5 is 45.5%). null when the kind is not included or PE cannot compute it.
        threshold:
          type:
            - number
            - "null"
          description: The non-FEOC threshold percent for the threshold year. null when FEOC does not apply.
        reason:
          type: string
          description: "Why FEOC does not apply, or why PE could not compute the percent. Present only then."
    Feoc:
      type: object
      additionalProperties: false
      required:
        - applies
        - pv
        - storage
      properties:
        applies:
          type: boolean
          description: "false when the threshold year is 2025 or earlier. FEOC rules start with construction in 2026."
        pv:
          $ref: "#/components/schemas/FeocCategory"
        storage:
          $ref: "#/components/schemas/FeocCategory"
    DcUnresolved:
      type: object
      additionalProperties: false
      required:
        - sku
        - category
        - code
        - message
      properties:
        sku:
          type: string
        category:
          $ref: "#/components/schemas/AvlCategory"
        code:
          type: string
          enum:
            - EQUIPMENT_NOT_ON_AVL
            - EQUIPMENT_AMBIGUOUS
        message:
          type: string
        matches:
          type: integer
          description: How many AVL items the SKU matches (EQUIPMENT_AMBIGUOUS).
    DomesticContent:
      type: object
      additionalProperties: false
      required:
        - year
        - thresholdBasis
        - bocDate
        - pv
        - storage
        - feoc
        - items
        - unresolved
      properties:
        year:
          type: integer
          description: "The year that set the thresholds. With a Safe Harbor beginning of construction date, this is the year of that date, not the `year` you sent."
        thresholdBasis:
          type: string
          enum:
            - boc
            - computeYear
          description: "boc: the Safe Harbor beginning of construction date set the thresholds. computeYear: year set them."
        bocDate:
          type:
            - string
            - "null"
          format: date
        pv:
          $ref: "#/components/schemas/DcSummary"
        storage:
          $ref: "#/components/schemas/DcSummary"
        feoc:
          $ref: "#/components/schemas/Feoc"
        items:
          type: array
          items:
            $ref: "#/components/schemas/DcItem"
        unresolved:
          type: array
          items:
            $ref: "#/components/schemas/DcUnresolved"
    ResolvedAddress:
      type: object
      additionalProperties: false
      required:
        - formatted
        - street
        - city
        - stateCode
        - zipCode
        - county
        - latitude
        - longitude
        - precision
        - partialMatch
      properties:
        formatted:
          type: string
          description: The full address as Google Maps writes it.
        street:
          type: string
          description: The street number and the street name. When `precision` is `street`, the street line you sent.
        city:
          type:
            - string
            - "null"
          description: The city. Null when Google returned no city.
        stateCode:
          type: string
          description: The 2-letter state code.
        zipCode:
          type:
            - string
            - "null"
          description: The 5-digit ZIP code. Null when Google returned no ZIP code.
        county:
          type:
            - string
            - "null"
          description: The county name, without the word County.
        latitude:
          type: number
        longitude:
          type: number
        precision:
          type: string
          enum:
            - rooftop
            - interpolated
            - street
          description: "How exactly Google placed the address. 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. Then jurisdiction.lowConfidence is true."
        partialMatch:
          type: boolean
          description: Google matched only part of the address you sent. Compare this address with your address before you use the result.
        mismatches:
          type: array
          description: "Since 2.2. Each field where Google's address differs from the address you sent. Empty when they agree. In POST /sales-tax, a mismatch sets jurisdiction.lowConfidence."
          items:
            type: object
            additionalProperties: false
            required:
              - field
              - sent
              - resolved
            properties:
              field:
                type: string
                enum:
                  - zipCode
                  - city
                  - stateCode
              sent:
                type: string
              resolved:
                type: string
      description: The site address as PE found it with Google Maps. PE runs the check on this address, not on the address you sent. When `precision` is `street`, PE uses the street line you sent with the city, state and ZIP code that Google found.
    SalesTaxCheckRequest:
      type: object
      additionalProperties: false
      required:
        - address
        - systemType
      properties:
        address:
          $ref: "#/components/schemas/Address"
        systemType:
          type: string
          enum:
            - solar_only
            - solar_battery
            - battery_only
        existingSolarOnProperty:
          type: boolean
          description: "battery_only: the property already has solar. It changes the sales tax in some states."
        contractDate:
          type: string
          description: "YYYY-MM-DD. Default: today in America/Los_Angeles."
          format: date
        netAmountDue:
          type: number
          description: Optional. With it, PE also returns the tax amount. From 1000 to 500000 US dollars (AMOUNT_OUT_OF_RANGE). 0 counts as left out (the rate only, no amount).
          minimum: 0
          maximum: 500000
    SalesTaxCheck:
      type: object
      additionalProperties: false
      required:
        - stateCode
        - taxStateCode
        - systemType
        - taxable
        - rate
        - baseRate
        - grossedUp
        - netAmountDue
        - amount
        - source
        - jurisdiction
        - components
        - asOfDate
        - note
        - resolvedAddress
      properties:
        stateCode:
          type: string
          description: The state you sent.
        taxStateCode:
          type: string
          description: The state of the tax rule.
        systemType:
          type: string
        taxable:
          type: boolean
          description: Whether PE collects lease sales tax here.
        rate:
          type: number
          description: The rate as a fraction.
        baseRate:
          type: number
          description: The rate before any gross up.
        grossedUp:
          type: boolean
          description: Whether the rate includes a pass-on gross up (Hawaii).
        netAmountDue:
          type:
            - number
            - "null"
        amount:
          type:
            - number
            - "null"
          description: netAmountDue x rate, when you sent netAmountDue and the lease is taxable.
        source:
          type: string
          description: Where the rate came from.
        jurisdiction:
          type: object
          additionalProperties: false
          required:
            - city
            - county
            - zipCode
            - lowConfidence
          properties:
            city:
              type:
                - string
                - "null"
            county:
              type:
                - string
                - "null"
            zipCode:
              type:
                - string
                - "null"
            lowConfidence:
              type: boolean
              description: "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` is true), Google placed only the street and not the house number (`resolvedAddress.precision` is `street`), or the Colorado state lookup placed the address only approximately. Check the address before you use the rate."
        components:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - name
              - type
              - rate
              - applied
            properties:
              name:
                type: string
              type:
                type: string
              rate:
                type: number
              applied:
                type: boolean
        asOfDate:
          type: string
          format: date
        note:
          type:
            - string
            - "null"
          description: A plain note when PE could not fully confirm the rate.
        resolvedAddress:
          $ref: "#/components/schemas/ResolvedAddress"
    EnergyCommunityRequest:
      type: object
      additionalProperties: false
      required:
        - address
      properties:
        address:
          $ref: "#/components/schemas/Address"
    EnergyCommunity:
      type: object
      additionalProperties: false
      required:
        - qualifies
        - category
        - itcBonus
        - countyFips
        - tractGeoid
        - resolvedAddress
      properties:
        qualifies:
          type: boolean
        category:
          type:
            - string
            - "null"
          enum:
            - statistical_area
            - coal_closure
            - null
        itcBonus:
          type: number
          description: The Energy Community bonus in percentage points (10 or 0).
        countyFips:
          type:
            - string
            - "null"
        tractGeoid:
          type:
            - string
            - "null"
        resolvedAddress:
          $ref: "#/components/schemas/ResolvedAddress"
    LeasePriceRequest:
      type: object
      additionalProperties: false
      required:
        - epcAmount
        - systemType
        - insuranceOption
        - address
        - pvDomesticContent
        - storageDomesticContent
        - energyCommunity
        - dcBonusRecipient
      properties:
        epcAmount:
          type: number
          description: The total EPC for the system before tax, in US dollars. From 1000 to 500000 (EPC_OUT_OF_RANGE).
          minimum: 1000
          maximum: 500000
        eligibleRoofingCost:
          type: number
          description: Roofing under the array, in USD. Default 0.
        ineligibleRoofingCost:
          type: number
          description: Other roofing, in USD. Default 0.
        systemType:
          type: string
          enum:
            - solar_only
            - solar_battery
            - battery_only
        insuranceOption:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: The homeowner's insurance option. See How PE prices a lease. Send a number; the strings "1", "2" and "3" are also accepted and read as numbers.
        address:
          $ref: "#/components/schemas/Address"
        pvDomesticContent:
          type: boolean
          description: The PV equipment meets Domestic Content.
        storageDomesticContent:
          type: boolean
          description: The storage equipment meets Domestic Content.
        energyCommunity:
          oneOf:
            - type: boolean
            - type: string
              const: auto
          description: true, false, or "auto" to run the Energy Community check on the address.
        dcBonusRecipient:
          type: string
          enum:
            - installer
            - customer
          description: Who gets the Domestic Content bonus at the 35% tier. Any case is accepted and read as lower case.
        includedIncentive:
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - none
                - hawaii_retitc
                - installer_managed
            amount:
              type: number
              description: "installer_managed only: the amount in USD, less than the EPC. With type none or hawaii_retitc, leave it out."
        safeHarbor:
          type: object
          additionalProperties: false
          required:
            - opportunityId
            - units
          properties:
            opportunityId:
              type: string
              description: From GET /safe-harbor/opportunities.
            units:
              type: integer
              description: Whole units, from 1 to the units available.
        existingSolarOnProperty:
          type: boolean
          description: "battery_only: the property already has solar. It changes the sales tax in some states."
        contractDate:
          type: string
          description: "YYYY-MM-DD. Default: today in America/Los_Angeles. From one year before today to 90 days after today (CONTRACT_DATE_OUT_OF_RANGE). Hawaii: on or after 2026-07-03 (CONTRACT_DATE_BEFORE_RETITC_CUTOFF)."
          format: date
        systemSizeKw:
          type: number
          description: "Optional, since 2.2. The DC size in kW, from 0.5 to 250. With it, the EPC must be from $1 to $10 per watt on solar_only, at least $1 per watt on solar_battery (the EPC also pays for the battery), no per watt check on battery_only. It does not change the numbers."
    SalesTax:
      type: object
      additionalProperties: false
      required:
        - rate
        - amount
        - taxable
        - source
        - needsAttention
      properties:
        rate:
          type: number
          description: The effective lease sales tax rate as a fraction.
        amount:
          type: number
          description: Net Amount Due x rate, or 0 when not taxable. USD, rounded to cents.
        taxable:
          type: boolean
        source:
          type: string
          enum:
            - CO-DOR-Avalara
            - STC
            - MANUAL
            - none
          description: Where the rate came from.
        needsAttention:
          type:
            - string
            - "null"
          description: A fixed note when PE could not fully confirm the rate, else null. The quote then also has a SALES_TAX_NEEDS_ATTENTION warning.
    LeaseInputsEcho:
      type: object
      additionalProperties: false
      required:
        - epcAmount
        - eligibleRoofingCost
        - ineligibleRoofingCost
        - systemType
        - insuranceOption
        - address
        - taxStateCode
        - pvDomesticContent
        - storageDomesticContent
        - energyCommunity
        - energyCommunitySource
        - energyCommunityCategory
        - dcBonusRecipient
        - includedIncentive
        - safeHarbor
        - existingSolarOnProperty
        - contractDate
        - systemSizeKw
      properties:
        epcAmount:
          type: number
        eligibleRoofingCost:
          type: number
        ineligibleRoofingCost:
          type: number
        systemType:
          type: string
          enum:
            - solar_only
            - solar_battery
            - battery_only
        insuranceOption:
          type: integer
          enum:
            - 1
            - 2
            - 3
        address:
          type: object
          additionalProperties: false
          required:
            - city
            - stateCode
            - zipCode
          properties:
            city:
              type: string
            stateCode:
              type: string
            zipCode:
              type: string
        taxStateCode:
          type: string
          description: The state PE used for the tax.
        pvDomesticContent:
          type: boolean
        storageDomesticContent:
          type: boolean
        energyCommunity:
          type: boolean
          description: The resolved value.
        energyCommunitySource:
          type: string
          enum:
            - request
            - ec_check
        energyCommunityCategory:
          type:
            - string
            - "null"
        dcBonusRecipient:
          type: string
          enum:
            - installer
            - customer
        includedIncentive:
          type: object
          additionalProperties: false
          required:
            - type
            - amount
          properties:
            type:
              type: string
              enum:
                - none
                - hawaii_retitc
                - installer_managed
            amount:
              type: number
        safeHarbor:
          oneOf:
            - type: object
              additionalProperties: false
              required:
                - opportunityId
                - units
                - unitCost
              properties:
                opportunityId:
                  type: string
                units:
                  type: integer
                unitCost:
                  type: number
            - type: "null"
        existingSolarOnProperty:
          type: boolean
        contractDate:
          type: string
          format: date
        systemSizeKw:
          type:
            - number
            - "null"
          description: The DC size you sent, or null. Since 2.2.
      description: The inputs PE priced, after defaults and lookups. insuranceOption and dcBonusRecipient are the normalized values. When PE's Energy Community lookup did not confirm energyCommunity true, energyCommunity is false and energyCommunitySource is ec_check.
    LeaseQuote:
      type: object
      additionalProperties: false
      required:
        - quoteId
        - leaseFactor
        - leaseDiscountPercent
        - tierLeaseFactor
        - insuranceRiskAdjustment
        - adjustedEpc
        - replacementCost
        - leaseDiscount
        - netAmountDue
        - leaseAmount
        - salesTax
        - insuranceRiderAmount
        - dcBonusAmount
        - safeHarborDeduction
        - pePayout
        - icPaymentGross
        - icPayment
        - pcPayment
        - inputsEcho
        - notes
        - warnings
      properties:
        quoteId:
          type: string
          description: For your logs only. It is not a project id. PE does not store it.
        leaseFactor:
          type: number
          description: The lease factor PE used for the discount (7 decimals). It is the baseline 1.4285714 when the installer keeps the Domestic Content bonus.
        leaseDiscountPercent:
          type: number
          description: The customer's discount in percent (30 is 30%).
        tierLeaseFactor:
          type: number
          description: The lease factor of the Domestic Content and Energy Community tier (7 decimals).
        insuranceRiskAdjustment:
          type: number
          description: "Insurance option 3: 2.5% of the EPC added to the EPC basis. USD, rounded to cents."
        adjustedEpc:
          type: number
          description: EPC + insurance adjustment + eligible roofing. USD, rounded to cents.
        replacementCost:
          type: number
          description: EPC + insurance adjustment + all roofing. USD, rounded to cents.
        leaseDiscount:
          type: number
          description: The customer's discount. USD, rounded to cents.
        netAmountDue:
          type: number
          description: What the customer pays, before lease sales tax. USD, rounded to cents.
        leaseAmount:
          type: number
          description: Replacement cost - lease discount, before included incentives. USD, rounded to cents.
        salesTax:
          $ref: "#/components/schemas/SalesTax"
        insuranceRiderAmount:
          type: number
          description: "Insurance option 3: 2.5% of the EPC taken from the IC payment. USD, rounded to cents."
        dcBonusAmount:
          type: number
          description: The Domestic Content bonus paid to the installer. USD, rounded to cents.
        safeHarborDeduction:
          type: number
          description: Safe Harbor units x unit cost. USD, rounded to cents.
        pePayout:
          type: number
          description: Lease discount + Domestic Content bonus + Hawaii RETITC. USD, rounded to cents.
        icPaymentGross:
          type: number
          description: (PE payout - Safe Harbor deduction) x 2/3. USD, rounded to cents.
        icPayment:
          type: number
          description: The Inspection Complete payment after lease sales tax and insurance. USD, rounded to cents.
        pcPayment:
          type: number
          description: "The Project Complete payment: (PE payout - Safe Harbor deduction) x 1/3. USD, rounded to cents."
        inputsEcho:
          $ref: "#/components/schemas/LeaseInputsEcho"
        notes:
          type: array
          items:
            type: string
          description: Plain sentences that explain the numbers.
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/PricingWarning"
    SungageProducts:
      type: object
      additionalProperties: false
      required:
        - stateCode
        - environment
        - isPrepaidTpoState
        - products
      properties:
        stateCode:
          type: string
        environment:
          type: string
          enum:
            - production
            - sandbox
          description: The Sungage environment PE used.
        isPrepaidTpoState:
          type: boolean
          description: False when Sungage has no Prepaid TPO card in the state. products is then empty.
        products:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - dppProduct
              - terms
            properties:
              dppProduct:
                type: string
                enum:
                  - Installment
                  - Classic DPP
                  - Escalator
              terms:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                    - term
                    - options
                  properties:
                    term:
                      type: integer
                      description: Years.
                    options:
                      type: array
                      items:
                        type: object
                        additionalProperties: false
                        required:
                          - rate
                          - isDefault
                        properties:
                          rate:
                            type: number
                            description: The loan rate in percent.
                          isDefault:
                            type: boolean
                          escalatorPercentage:
                            type: number
                            description: "Escalator only: the yearly payment increase in percent."
    SungagePriceRequest:
      type: object
      additionalProperties: false
      required:
        - epcAmount
        - systemType
        - insuranceOption
        - address
        - pvDomesticContent
        - storageDomesticContent
        - energyCommunity
        - dcBonusRecipient
        - dppProduct
        - term
        - rate
      properties:
        epcAmount:
          type: number
          description: The total EPC for the system before tax, in US dollars. From 1000 to 500000 (EPC_OUT_OF_RANGE).
          minimum: 1000
          maximum: 500000
        eligibleRoofingCost:
          type: number
          description: Roofing under the array, in USD. Default 0.
        ineligibleRoofingCost:
          type: number
          description: Other roofing, in USD. Default 0.
        systemType:
          type: string
          enum:
            - solar_only
            - solar_battery
            - battery_only
        insuranceOption:
          type: integer
          enum:
            - 1
            - 2
            - 3
          description: The homeowner's insurance option. See How PE prices a lease. Send a number; the strings "1", "2" and "3" are also accepted and read as numbers.
        address:
          $ref: "#/components/schemas/Address"
        pvDomesticContent:
          type: boolean
          description: The PV equipment meets Domestic Content.
        storageDomesticContent:
          type: boolean
          description: The storage equipment meets Domestic Content.
        energyCommunity:
          oneOf:
            - type: boolean
            - type: string
              const: auto
          description: true, false, or "auto" to run the Energy Community check on the address.
        dcBonusRecipient:
          type: string
          enum:
            - installer
            - customer
          description: Who gets the Domestic Content bonus at the 35% tier. Any case is accepted and read as lower case.
        includedIncentive:
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - none
                - hawaii_retitc
                - installer_managed
            amount:
              type: number
              description: "installer_managed only: the amount in USD, less than the EPC. With type none or hawaii_retitc, leave it out."
        safeHarbor:
          type: object
          additionalProperties: false
          required:
            - opportunityId
            - units
          properties:
            opportunityId:
              type: string
              description: From GET /safe-harbor/opportunities.
            units:
              type: integer
              description: Whole units, from 1 to the units available.
        existingSolarOnProperty:
          type: boolean
          description: "battery_only: the property already has solar. It changes the sales tax in some states."
        contractDate:
          type: string
          description: "YYYY-MM-DD. Default: today in America/Los_Angeles. From one year before today to 90 days after today (CONTRACT_DATE_OUT_OF_RANGE). Hawaii: on or after 2026-07-03 (CONTRACT_DATE_BEFORE_RETITC_CUTOFF)."
          format: date
        systemSizeKw:
          type: number
          description: "Optional, since 2.2. The DC size in kW, from 0.5 to 250. With it, the EPC must be from $1 to $10 per watt on solar_only, at least $1 per watt on solar_battery (the EPC also pays for the battery), no per watt check on battery_only. It does not change the numbers."
        dppProduct:
          type: string
          enum:
            - Installment
            - Classic DPP
            - Escalator
        term:
          type: integer
          enum:
            - 5
            - 10
            - 15
            - 20
            - 25
            - 30
          description: "Years (not months): 5, 10, 15, 20 or 25, and at most 10 for battery_only."
        rate:
          type: number
          description: The loan rate in percent, from GET /pricing/sungage/products.
          minimum: 0
    SungageQuote:
      type: object
      additionalProperties: false
      required:
        - quoteId
        - environment
        - sungage
        - loan
        - installerPayments
        - installerTotals
        - pricingChecksPassed
        - warnings
        - lease
      properties:
        quoteId:
          type: string
          description: For your logs only. It is not a project id.
        environment:
          type: string
          enum:
            - production
            - sandbox
          description: The Sungage environment PE used.
        sungage:
          type: object
          additionalProperties: false
          required:
            - stateCode
            - dppProduct
            - term
            - rate
          properties:
            stateCode:
              type: string
            dppProduct:
              type: string
              enum:
                - Installment
                - Classic DPP
                - Escalator
            term:
              type: integer
            rate:
              type: number
        loan:
          type: object
          additionalProperties: false
          required:
            - epcAmount
            - insuranceRate
            - insuranceAmount
            - eligibleRoofCost
            - adjustedEpc
            - leaseFactor
            - leaseDiscountPercent
            - leaseDiscount
            - ineligibleRoofFinanced
            - customerNad
            - salesTaxRate
            - salesTaxAmount
            - loanAmount
            - estimatedMonthlyPayment
            - escalatorPercentage
            - paymentsNote
          properties:
            epcAmount:
              type: number
            insuranceRate:
              type: number
              description: Fraction. 0 unless insurance option 3.
            insuranceAmount:
              type: number
              description: Insurance option 3 amount. USD, rounded to cents.
            eligibleRoofCost:
              type: number
            adjustedEpc:
              type: number
              description: The adjusted EPC for the loan. USD, rounded to cents.
            leaseFactor:
              type: number
              description: 7 decimals.
            leaseDiscountPercent:
              type: number
              description: The discount in percent.
            leaseDiscount:
              type: number
            ineligibleRoofFinanced:
              type: number
              description: Ineligible roofing as financed. USD, rounded to cents.
            customerNad:
              type: number
              description: The customer's Net Amount Due. USD, rounded to cents.
            salesTaxRate:
              type: number
            salesTaxAmount:
              type: number
            loanAmount:
              type: number
              description: The loan amount to apply for. USD, rounded to cents.
            estimatedMonthlyPayment:
              type:
                - number
                - "null"
              description: From Sungage, or null when Sungage could not quote it.
            escalatorPercentage:
              type:
                - number
                - "null"
              description: Escalator only.
            paymentsNote:
              type:
                - string
                - "null"
              description: Why there is no monthly payment.
        installerPayments:
          type: object
          additionalProperties: false
          required:
            - sungageFundsInstaller
            - leaseDiscount
            - dcBonusAmount
            - pePayoutGross
            - safeHarborDeduction
            - payoutBase
            - paymentAtICGross
            - salesTaxAmount
            - insuranceAmount
            - paymentAtIC
            - paymentAtPC
          properties:
            sungageFundsInstaller:
              type: number
              description: What Sungage pays the installer. USD, rounded to cents.
            leaseDiscount:
              type: number
            dcBonusAmount:
              type: number
            pePayoutGross:
              type: number
              description: The balance payment from PE. USD, rounded to cents.
            safeHarborDeduction:
              type: number
            payoutBase:
              type: number
              description: The PE payout after Safe Harbor. USD, rounded to cents.
            paymentAtICGross:
              type: number
              description: payoutBase x 2/3.
            salesTaxAmount:
              type: number
            insuranceAmount:
              type: number
            paymentAtIC:
              type: number
              description: The net IC payment. USD, rounded to cents.
            paymentAtPC:
              type: number
              description: The PC payment. USD, rounded to cents.
        installerTotals:
          type: object
          additionalProperties: false
          required:
            - installerFromSungage
            - installerFromPe
            - installerTotal
          properties:
            installerFromSungage:
              type: number
            installerFromPe:
              type: number
            installerTotal:
              type: number
        pricingChecksPassed:
          type: boolean
          description: False means the numbers did not reconcile. Do not use the quote; contact PE.
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/PricingWarning"
        lease:
          $ref: "#/components/schemas/LeaseQuote"
    CreateUploadRequest:
      type: object
      additionalProperties: false
      required:
        - vendorProjectId
        - stateCode
        - fileName
        - sizeBytes
      properties:
        vendorProjectId:
          type: string
          description: Your id for the project. One upload only.
          pattern: ^[A-Za-z0-9_.:-]{1,128}$
        stateCode:
          type: string
          description: The project state.
          pattern: ^[A-Za-z]{2}$
        productType:
          type: string
          const: Synthetic Cash
          description: Default Synthetic Cash. Other values return PRODUCT_NOT_SUPPORTED.
        fileName:
          type: string
          description: Ends in .pdf. No slashes.
          maxLength: 200
        sizeBytes:
          type: integer
          description: The file size.
          minimum: 1
          maximum: 26214400
        sandboxScenario:
          $ref: "#/components/schemas/SandboxScenario"
    CreatedUpload:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - uploadUrl
        - uploadMethod
        - uploadHeaders
        - uploadExpiresAt
        - status
      properties:
        uploadId:
          type: string
        uploadUrl:
          type: string
          description: A signed URL. PUT the PDF here within 15 minutes, once. Send no Authorization header.
          format: uri
        uploadMethod:
          type: string
          const: PUT
        uploadHeaders:
          type: object
          additionalProperties:
            type: string
          required:
            - Content-Type
            - x-goog-if-generation-match
            - x-goog-content-length-range
          properties:
            Content-Type:
              type: string
              const: application/pdf
            x-goog-if-generation-match:
              type: string
              const: "0"
            x-goog-content-length-range:
              type: string
              pattern: "^[0-9]+,[0-9]+$"
              description: "Since 2.2: sizeBytes,sizeBytes. The PUT body must be exactly the sizeBytes you declared."
              examples:
                - 120000,120000
          description: Send EVERY header here on the PUT, with these exact values. PE can add headers; send all of them.
        uploadExpiresAt:
          type: string
          format: date-time
        status:
          type: string
          const: awaiting_file
    SubmittedUpload:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - status
      properties:
        uploadId:
          type: string
        status:
          type: string
          const: queued
    UploadCheck:
      type: object
      additionalProperties: false
      required:
        - checkId
        - status
        - message
      properties:
        checkId:
          type: string
        status:
          type: string
          enum:
            - fail
            - warn
        message:
          type: string
          description: The text the installer sees.
    Upload:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - vendorProjectId
        - status
        - submittedAt
        - completedAt
      properties:
        uploadId:
          type: string
        vendorProjectId:
          type: string
        status:
          $ref: "#/components/schemas/UploadStatus"
        outcome:
          $ref: "#/components/schemas/UploadOutcome"
        outcomeMessage:
          type: string
          description: Show it to your user.
        nextStep:
          type: string
          description: Show it to your user.
        project:
          type: object
          additionalProperties: false
          required:
            - projectId
            - status
            - milestone
            - documentReviewStatus
          properties:
            projectId:
              type: string
              description: The PE Project ID.
            status:
              type:
                - string
                - "null"
            milestone:
              type:
                - string
                - "null"
            documentReviewStatus:
              type:
                - string
                - "null"
          description: Present when the upload created a project.
        checks:
          type: array
          items:
            $ref: "#/components/schemas/UploadCheck"
          description: Failed checks and warnings. Present only when there are some.
        submittedAt:
          type:
            - string
            - "null"
          format: date-time
        completedAt:
          type:
            - string
            - "null"
          format: date-time
    ProjectAction:
      type: object
      additionalProperties: false
      required:
        - title
        - detail
        - createdAt
      properties:
        title:
          type: string
        detail:
          type: string
        document:
          type:
            - string
            - "null"
          description: The document the Action is about, or null.
        createdAt:
          type:
            - string
            - "null"
          format: date-time
    ProjectStatus:
      type: object
      additionalProperties: false
      required:
        - projectId
        - vendorProjectId
        - environment
        - installer
        - status
        - milestone
        - documentReviewStatus
        - actionsRequired
        - icApproval
        - pcApproval
        - createdAt
        - updatedAt
      properties:
        projectId:
          type: string
          description: The PE Project ID. Test ids start with SBX-.
        vendorProjectId:
          type: string
        environment:
          $ref: "#/components/schemas/Environment"
        installer:
          $ref: "#/components/schemas/Installer"
        status:
          type:
            - string
            - "null"
          description: For example Active, At-risk, On Hold, Cancelled, Completed.
        milestone:
          type:
            - string
            - "null"
          description: For example Project Onboarded, Inspection Complete, Project Complete.
        documentReviewStatus:
          type:
            - string
            - "null"
          description: Action Required (Installer), Under Review (PE) or Approved.
        actionsRequired:
          type: array
          items:
            $ref: "#/components/schemas/ProjectAction"
        icApproval:
          $ref: "#/components/schemas/Approval"
        pcApproval:
          $ref: "#/components/schemas/Approval"
        createdAt:
          type:
            - string
            - "null"
          format: date-time
        updatedAt:
          type:
            - string
            - "null"
          format: date-time
    WebhookEventType:
      type: string
      enum:
        - project.ic_approved
        - project.pc_approved
    SetWebhookRequest:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          description: An https URL on port 443 with a public host name.
          maxLength: 2048
          format: uri
    WebhookWithSecret:
      type: object
      additionalProperties: false
      required:
        - url
        - signingSecret
        - events
      properties:
        url:
          type:
            - string
            - "null"
          format: uri
        signingSecret:
          type: string
          description: Store it. PE shows it only here.
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
    Webhook:
      type: object
      additionalProperties: false
      required:
        - url
        - events
      properties:
        url:
          type:
            - string
            - "null"
          format: uri
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
    WebhookDeleted:
      type: object
      additionalProperties: false
      required:
        - url
        - deleted
      properties:
        url:
          type: "null"
        deleted:
          type: boolean
          const: true
    WebhookTestResult:
      type: object
      additionalProperties: false
      required:
        - delivered
        - statusCode
        - durationMs
      properties:
        delivered:
          type: boolean
        statusCode:
          type:
            - integer
            - "null"
          description: Your endpoint's HTTP status.
        durationMs:
          type: integer
        error:
          type: string
          description: Why the delivery failed.
    SimulateRequest:
      type: object
      additionalProperties: false
      required:
        - event
      properties:
        event:
          $ref: "#/components/schemas/SimulateEvent"
    ApprovalEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - createdAt
        - environment
        - data
      properties:
        id:
          type: string
          description: The event id. Also in PE-Webhook-Id.
        type:
          $ref: "#/components/schemas/WebhookEventType"
        createdAt:
          type: string
          format: date-time
        environment:
          $ref: "#/components/schemas/Environment"
        data:
          type: object
          additionalProperties: false
          required:
            - projectId
            - vendorProjectId
            - grantId
            - milestone
          properties:
            projectId:
              type: string
            vendorProjectId:
              type: string
            grantId:
              type: string
              description: Your grant for the installer.
            milestone:
              type:
                - string
                - "null"
            icApproval:
              $ref: "#/components/schemas/Approval"
            pcApproval:
              $ref: "#/components/schemas/Approval"
          description: project.ic_approved has icApproval. project.pc_approved has pcApproval.
    PingEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - createdAt
        - environment
        - data
      properties:
        id:
          type: string
        type:
          type: string
          const: ping
        createdAt:
          type: string
          format: date-time
        environment:
          $ref: "#/components/schemas/Environment"
        data:
          type: object
          additionalProperties: false
          required: []
          properties: {}
    TokenResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Token"
        meta:
          $ref: "#/components/schemas/Meta"
    ExchangeResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Exchange"
        meta:
          $ref: "#/components/schemas/Meta"
    GrantResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Grant"
        meta:
          $ref: "#/components/schemas/Meta"
    GrantRevokedResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/GrantRevoked"
        meta:
          $ref: "#/components/schemas/Meta"
    PingResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Ping"
        meta:
          $ref: "#/components/schemas/Meta"
    AvlPageResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/AvlPage"
        meta:
          $ref: "#/components/schemas/Meta"
    SafeHarborOpportunityListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SafeHarborOpportunityList"
        meta:
          $ref: "#/components/schemas/Meta"
    CustomAvlListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/CustomAvlList"
        meta:
          $ref: "#/components/schemas/Meta"
    StateListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/StateList"
        meta:
          $ref: "#/components/schemas/Meta"
    UtilityListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/UtilityList"
        meta:
          $ref: "#/components/schemas/Meta"
    EligibilityResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Eligibility"
        meta:
          $ref: "#/components/schemas/Meta"
    DomesticContentResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/DomesticContent"
        meta:
          $ref: "#/components/schemas/Meta"
    SalesTaxCheckResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SalesTaxCheck"
        meta:
          $ref: "#/components/schemas/Meta"
    EnergyCommunityResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/EnergyCommunity"
        meta:
          $ref: "#/components/schemas/Meta"
    LeaseQuoteResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/LeaseQuote"
        meta:
          $ref: "#/components/schemas/Meta"
    SungageProductsResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SungageProducts"
        meta:
          $ref: "#/components/schemas/Meta"
    SungageQuoteResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SungageQuote"
        meta:
          $ref: "#/components/schemas/Meta"
    CreatedUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/CreatedUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    SubmittedUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SubmittedUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    UploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Upload"
        meta:
          $ref: "#/components/schemas/Meta"
    ProjectStatusResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ProjectStatus"
        meta:
          $ref: "#/components/schemas/Meta"
    WebhookWithSecretResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/WebhookWithSecret"
        meta:
          $ref: "#/components/schemas/Meta"
    WebhookResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Webhook"
        meta:
          $ref: "#/components/schemas/Meta"
    WebhookDeletedResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/WebhookDeleted"
        meta:
          $ref: "#/components/schemas/Meta"
    WebhookTestResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/WebhookTestResult"
        meta:
          $ref: "#/components/schemas/Meta"
