# Participate Energy Installer API v2 (files/api/SPEC-installer-api-v2.md section 13).
# Source of truth. openapi.json is generated from this file by
# scripts/gen-installer-openapi-json.cjs; run it after every edit.
# The operations, the ErrorCode, UploadOutcome, Scope, SandboxScenario and
# SimulateEvent enums, the upload headers and the error docs are pinned to
# the code by functions/src/api/installerv2/openapi.test.ts.
# Synthetic examples only: no real names, addresses, ids or secrets.
openapi: 3.1.0
info:
  title: Participate Energy Installer API
  version: 2.2.0
  description: |-
    The Participate Energy (PE) Installer API connects your CRM or your own tools to PE. You are a PE install partner. With one API key, your software can do these tasks:

    - Read the Approved Vendor List (AVL), your Safe Harbor opportunities, your states, the utilities of a ZIP code, your Equipment Map and PE's reference lists.
    - Check whether a site is eligible. 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 agreement.
    - Prefill Contract Builder drafts for your sales reps (customer, site, system, equipment, lease price and payments), checked with the builder's own rules, and send them for e-signature.
    - List and read your projects: customer, site, dates, approvals, financials, equipment, documents, photos, Actions and activity.
    - Update the project fields that you can edit in the Installer Portal, the financials, the equipment and the Safe Harbor opportunity.
    - Upload documents and photos, read the review feedback, and save monitoring site IDs.
    - Read and resolve Actions.
    - Get webhooks when PE approves Inspection Complete (IC) and Project Complete (PC), and when the e-sign status of a contract changes.

    The API does what the Installer Portal does, with the same rules. When the API and the portal disagree, contact PE.

    **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.
    2. Match your equipment to AVL SKUs in your own system. `GET /equipment-map` shows how your past equipment strings resolve.
    3. Check the site with `POST /eligibility`, Domestic Content and FEOC with `POST /checks/domestic-content`, Energy Community with `POST /checks/energy-community`, and the sales tax rate with `POST /checks/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: prefill a contract draft with `POST /contract-drafts`, then send it for e-signature with `POST /contract-drafts/{draftId}/send`, or let the rep open it in the Contract Builder and send it from the portal (see Contract drafts and e-sign). Or have the customer sign your own contract and send it with a contract upload (`POST /contract-uploads`).

    ## What changed in 2.2

    Version 2.2 adds input guardrails. Every change is new information or a refusal of input that was already wrong. No response field was removed or renamed.

    - Amounts are checked for their unit. `epcAmount` on `POST /pricing/lease`, `POST /pricing/sungage` and `PUT /projects/{projectId}/financials` must be from 1,000 to 500,000 USD (the total EPC), and so must `targetNetAmountDue`, which stands in for it: `EPC_OUT_OF_RANGE`, with a hint when the amount looks like cents, thousands of dollars or a price per watt. `netAmountDue` on `POST /checks/sales-tax` takes the same range (`AMOUNT_OUT_OF_RANGE`).
    - `POST /pricing/lease` and `POST /pricing/sungage` take an optional `systemSizeKw` (kW DC). With it, an EPC below $1 or above $10 per watt is refused (`EPC_PER_WATT_OUT_OF_RANGE`) 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.
    - A system size is in kW DC, from 0.5 to 250, and PE never converts it. A value that looks like watts returns `SYSTEM_SIZE_LOOKS_LIKE_WATTS`; any other value outside the range returns `SYSTEM_SIZE_OUT_OF_RANGE`. `PUT /projects/{projectId}/equipment` also refuses a `systemSizeKw` more than 25% away from the module count times the module wattage (`SYSTEM_SIZE_MISMATCH`) and a module quantity above 500 (`EQUIPMENT_QUANTITY_OUT_OF_RANGE`).
    - `contractDate` on pricing must be from one year before today to 90 days after today (`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`).
    - A site address cannot be a PO Box (`ADDRESS_PO_BOX`) on pricing, eligibility and the Energy Community and sales tax checks. A mailing address can be a PO Box.
    - Every lease quote has `warnings`, an empty array when there is none. New warning codes: `ENERGY_COMMUNITY_NOT_CONFIRMED` (you sent `energyCommunity: true`, the Energy Community check says the address does not qualify, and the quote uses false), `ENERGY_COMMUNITY_NOT_VERIFIED` (the check could not run, so the quote uses true as sent), `ROOFING_COST_HIGH` (a roofing cost is more than the EPC) and `FIELD_NOT_APPLICABLE` (a flag that does not apply to the system type). A warning never stops the quote.
    - Pricing refuses an `installer_managed` incentive that is not less than the EPC (`INCENTIVE_OUT_OF_RANGE`), a non-zero `includedIncentive.amount` with type `none` (`VALIDATION_FAILED`; `0` is accepted), and a roofing cost on `battery_only` (`ROOFING_COST_NOT_APPLICABLE`).
    - `insuranceOption` takes the number or the string (`1` or `"1"`), and `dcBonusRecipient` takes any case, on pricing and on `PUT /projects/{projectId}/financials`. Pricing answers with the number and lower case; the financials keep the forms the project stores (`"1"`, `Installer`).
    - `PUT /projects/{projectId}/financials` refuses a lender that is not on PE's approved lender list for the project's state (`LENDER_NOT_APPROVED`, with the approved names in `details`). Inputs that give a payout PE cannot make now return `FINANCIALS_INVALID` with the computed payout, not a server error.
    - `PUT /projects/{projectId}/equipment` refuses a battery on a Solar Only project (`SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER`): it changes the system type, which needs a change order.
    - `GET /contract-drafts/defaults` takes an optional `utility` and lists the state's included incentives without a utility filter when it is left out, so an incentive that needs a utility is no longer missing. `DRAFT_FIELD_REQUIRED` for an included incentive amount names the incentive (`incentiveId`).
    - `PUT /projects/{projectId}/equipment` also refuses a `systemSizeKw` that no module of 250 W to 1,000 W could give for the module count when the module wattage is not known (`SYSTEM_SIZE_MISMATCH`). `GET /utilities` and contract draft ZIP codes take ZIP+4.
    - A Hawaii `contractDate` before 2026-07-03 is refused (`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`) on pricing and on contract drafts.
    - `PATCH /projects/{projectId}` answers `FIELD_NOT_EDITABLE` with the reason for `productType`, `contractType`, `systemType`, `site` and `status`. `mailingAddress.state` must be a US state code (or a military post code AA, AE, AP, or a territory PR, VI, GU, AS, MP), and `mailingAddress.zipCode` takes ZIP+4 (PE stores the 5 digits). `GET /utilities` takes ZIP+4 too.
    - `PUT /projects/{projectId}/safe-harbor` supports `?dryRun=true`.
    - `GET /pricing/sungage/products` refuses a state code that is not a US state (`VALIDATION_FAILED`) or a state where PE does not operate (`STATE_NOT_SUPPORTED`) instead of answering `SUNGAGE_UNAVAILABLE`. `POST /checks/sales-tax` also answers `STATE_NOT_SUPPORTED` for a state where PE does not operate.
    - `POST /checks/sales-tax` and `POST /checks/energy-community`: when Google resolves the address to another ZIP code, city or state than you sent, `resolvedAddress.mismatches` lists each one, and the sales tax `jurisdiction.lowConfidence` is true.
    - `POST /checks/domestic-content` refuses a SKU sent under another category than its AVL category (`EQUIPMENT_CATEGORY_MISMATCH`) and a quantity above 500 (`EQUIPMENT_QUANTITY_OUT_OF_RANGE`).
    - Files: an empty file returns `FILE_EMPTY` (documents and photos) or `UPLOAD_FILE_EMPTY` (contract uploads). `FILE_CONTENT_MISMATCH` names the type the first bytes look like. A document `fileName` must end in an extension of its `contentType` (`.pdf` for a PDF).
    - Clearer errors: a `VALIDATION_FAILED` detail keeps the field's own hint (for example "contractDate must be YYYY-MM-DD", or a 4-digit ZIP code that lost its leading zero). `UNKNOWN_FIELD` details, and a document type, photo category or simulate document type near miss, carry `didYouMean`. A 404 for an id that matches one of your projects in another letter case names the exact id; ids stay case-sensitive.
    - An id in `resolveActionIds` that cannot be an Action id (for example one with a `/`) is returned in `skippedActionIds` instead of failing the confirm.
    - Contract drafts (new scope `contracts:write`): `POST /contract-drafts` prefills a Contract Builder draft for one of your sales reps from your company's prefill, prices the lease and validates it with the builder's rules; `GET`, `PATCH`, `DELETE` and `POST /contract-drafts/{draftId}/validate` manage it, and `GET /contract-drafts/defaults` shows your prefill for a state. See Contract drafts and e-sign.
    - Contract e-sign (new scope `contracts:send`): `POST /contract-drafts/{draftId}/send` creates the project from a draft and emails the contract to the homeowner for e-signature. `GET /projects/{projectId}/contract-esign` reads the contract and its signers, `POST /projects/{projectId}/contract-esign/send` sends it again and `POST /projects/{projectId}/contract-esign/void` voids it. The new webhook event `project.contract_status_changed` reports each change. Test keys render the real contract PDF and simulate the signing with the new `contract_*` simulate events. `POST /contract-esign` now returns `CONTRACT_ESIGN_MOVED` (410). See Contract drafts and e-sign.
    - Contract drafts: `validation.readyToSend` now means the send will not refuse the draft for its agreement. Validation (create, `PATCH`, `?dryRun=true` and `POST /contract-drafts/{draftId}/validate`) runs the agreement checks the send runs: an agreement published for the state (`CONTRACT_TEMPLATE_NOT_FOUND`), a place for the cosigner to sign (`COSIGNER_NOT_SUPPORTED`), a default signer (`AUTO_SIGNER_REQUIRED`), and every mandatory field of the agreement, named by its label and the body field that fills it (`DRAFT_FIELD_REQUIRED`, for example `sales.salesRepLicense` in California or `stateFields.mpucProjectLevel` in Maine), or `CONTRACT_DATA_MISSING` for a value from your company's settings. A send runs the same checks before it creates the project, so a missing agreement field returns `DRAFT_NOT_READY` and the draft stays editable; no project is left without a contract. `GET /contract-drafts/defaults` has `contractTemplate` (`available`, `cosignerAllowed`, `requiredFields`) and marks a state field the agreement requires as `required`. An error message never shows an internal agreement field id.
    - `PREFILL_INCENTIVE_NOT_APPLICABLE` has a `reason`. Only `not_offered_in_state` and `wrong_incentive_list` are prefill errors that ask for a prefill change; `system_type`, `utility` and `contract_date` (the Hawaii RETITC on a contract dated on or after 2026-07-03) mean a correct prefill whose incentive this draft rules out, and the message says no change is needed. `defaults.includedIncentives` and `defaults.incentives` list only the prefill incentives the state offers (with the utility, when sent), for a PV+Storage system on today's date.
    - New draft issues: a PV+Storage or Storage Only draft needs a battery line (`DRAFT_FIELD_REQUIRED` on `equipment[battery]`), a battery on a Solar Only draft is `EQUIPMENT_NOT_FOR_SYSTEM_TYPE` (was a `VALIDATION_FAILED` refusal), an install start before the contract date is `INSTALL_BEFORE_CONTRACT`, and a financed contract needs the lender name. Payment 1 is capped in whole cents ($1,000.01 is over the $1,000.00 cap). The cosigner phone follows the customer's rule, and an 11-digit phone (customer, cosigner, sales rep) must start with 1. ZIP code 00000 is refused. System Size AC is at most 50 kW, checked on the inverters' total in W (50,001 W is over). A 0 sent for a state field whose minimum is 0 (for example `batteryMinSoc` in California or `txBlendedUtilityRate` in Texas) counts as a value.
    - Draft body checks: money amounts (`epcAmount`, `payments`, `additionalProducts`, `includedIncentives` and `incentives` amounts) take at most 2 decimals; names (`customer`, `cosigner`, `sales.salesRepName`) cannot hold line breaks, tabs or other control characters; a number or currency state field takes 0 or more unless `GET /contract-drafts/defaults` gives another `min`; `coQtyOfPayments`, `ncQtyOfPayments` (a whole number from 1 to 4), `coMonthlyFixedUtilityCharges` (0 or more, at most 2 decimals, kept with 2) and `coUtilityRateEscalator`, `txUtilityRateEscalator` (0 to 100) take a number or numeric text, without the $ or % the agreement prints; a module `wattsDc` that differs from the AVL item's wattage is refused. A JSON number too large to read (`1e999`) is reported as "This field must be a finite number." "POB" is a PO Box.
    - Sizes: exactly 25% away from the module count times the wattage is accepted on both sides (`SYSTEM_SIZE_MISMATCH`). `PUT /projects/{projectId}/equipment` applies the 25% rule with the project's stored module wattage when the AVL item has none. On a draft, the PV system size is the module count times the wattage; its issue names that size, the modules and the `system.systemSizeKw` you sent. Error `details` name draft body fields (`financials.includedIncentives[0].amount`, `system.systemSizeKw`, `equipment[battery].outputPowerW` on Storage Only).
    - Contract drafts check the site ZIP code against PE's ZIP list: a ZIP code the list puts in another state is the warning `ZIP_CODE_NOT_IN_STATE` (it does not block the send), and a utility the ZIP code does not list is the warning `UTILITY_NOT_SERVING_ZIP`. On `PATCH`, a `null` in `stateFields` clears the field exactly as on create (blank, never the form default), and a key the draft holds that is not a field of its state (for example after a change of `siteAddress.stateCode`) is kept but not used, and never blocks the `PATCH`. A battery line on a Solar Only draft is `EQUIPMENT_NOT_FOR_SYSTEM_TYPE` on `POST /contract-drafts/{draftId}/validate` and on the send too, not only on create and `PATCH`. When PE cannot read the state's contract fields, the draft endpoints answer `STATE_FIELDS_UNAVAILABLE` (503, retry) and change nothing.
    - `POST /projects/{projectId}/contract-esign/send` refuses a signed (completed) contract (`CONTRACT_ALREADY_SIGNED`, 409) instead of sending a second one. A repeated `POST /contract-drafts/{draftId}/send` returns the contract's current `status` and signers (for example `voided`, with a `PACKET_NOT_OPEN` warning and `installerSigningUrl` `null`), not the status of the first answer. `GET /contract-drafts/defaults` gives each number or currency state field `zeroAllowed` (whether a 0 counts as a value). When PE cannot run the agreement checks for a moment, a draft gets the warning `CONTRACT_CHECKS_UNAVAILABLE` instead of nothing. An agreement field with a default value, or one filled from several draft fields (for example first and last name), is required only when the agreement would print it blank.

    ## What changed in 2.1

    - `GET /utilities` lists the utilities of a ZIP code. Send `zipCode` (5 digits). The `stateCode` parameter is gone: PE no longer lists every utility in a state.
    - `POST /checks/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 /checks/sales-tax` and `POST /checks/energy-community` resolve the site address with Google Maps and return `resolvedAddress`.
    - `POST /checks/energy-community`, and `POST /checks/sales-tax` in Colorado, now need a street address that Google can place: a street number and a street. Outside Colorado, `POST /checks/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 checks return the new error `ADDRESS_LOOKUP_UNAVAILABLE` (503). Send the same request again later.
    - In `POST /checks/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.
    - A new webhook event, `project.action_created`, tells you when PE creates an Action on one of your projects.

    ## Quick start

    Do these steps in the Test environment first. PE sends you a Test key in your onboarding email.

    1. **Call ping.** The response shows your company, the environment and the scopes of the key.

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

    2. **Read the AVL.** See `GET /avl`.

       ```bash
       curl "https://api.participate.energy/v2/installer/avl?category=pv_module&limit=5" \
         -H "Authorization: Bearer $PE_API_KEY"
       ```

    3. **Price a lease.** See `POST /pricing/lease`.
    4. **Upload a test contract.** Create the upload, PUT the PDF to the upload URL, then submit it. In the Test environment you choose the result with `sandboxScenario`. See Contract uploads.
    5. **Read the project.** Read the PE Project ID from `GET /contract-uploads/{uploadId}`. Then call `GET /projects/{projectId}`.
    6. **Move the project through its life.** Use `POST /sandbox/projects/{projectId}/simulate` to approve documents, raise Actions and approve IC and PC. Set a webhook URL to receive the approval and Action events.

    When every scope you need works in the Test environment, ask PE for a production key.

    ## Base URL and requests

    - The base URL is `https://api.participate.energy/v2/installer`. It is the same for Test and production keys.
    - Call the API from your servers only. The API does not support CORS. Never put a key in a browser, a mobile app or a public repository.
    - Send JSON with `Content-Type: application/json`. The body limit is 1 MiB.
    - Field names are camelCase.
    - PE rejects unknown fields with `UNKNOWN_FIELD`. This applies to the body and to the query string.
    - Money is a JSON number in US dollars, rounded to cents. Rates are fractions: `0.0825` is 8.25%. A field name that ends in `Percent` holds a 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: no-store`.
    - Responses never contain internal database ids. Every id in this API is a public id: a PE Project ID, an `uploadId`, an `actionId` and so on.
    - Your client must accept new optional response fields and new enum values.

    ## Keys and environments

    PE issues the keys. You do not create keys yourself: ask PE (your PE account manager, or raceway.support@participate.energy) for a key.

    | Item | Format | Notes |
    |---|---|---|
    | Test key | `ik_test_` and 40 letters and digits | Works only in the Test environment. |
    | Production key | `ik_live_` and 40 letters and digits | Works only in production. |
    | Grant ID | `igr_` and 20 letters and digits | The public id of a key. It is not secret. PE records it on the projects that the key creates. |

    - Send the key on every call: `Authorization: Bearer <key>`.
    - PE shows a key once, when PE creates it. PE stores only a hash. If you lose a key, ask PE for a new one.
    - A key lasts 12 months. Then it returns `KEY_EXPIRED`. Ask PE for a new key before that date.
    - Your company can have at most 5 active keys in each environment. Use a separate key for each system that calls the API.
    - A key has a set of scopes. See Scopes.
    - When PE revokes a key, or suspends your company's access, the change takes effect within 60 seconds.
    - An Installer API v1 key (`pk_...`) does not work here (`KEY_IS_V1`). A Design API credential (`dc_...`) does not work here (`KEY_IS_DESIGN_API`).

    The environment comes from the key:

    - **Test (`ik_test_`).** Writes go to a separate Test environment. They never reach PE operations. No PE reviewer sees a Test project or file. Contract review and document review are simulated: you choose the results with `sandboxScenario` and with the simulate endpoint. A Test project ID starts with `SBX-`, so it can never match a production ID. Test projects and uploads are deleted after 90 days. Test files are deleted after 30 days.
    - **Production (`ik_live_`).** Writes change real projects. PE reviews every contract and every document.
    - **Reference data is production data in both environments.** The AVL, Safe Harbor opportunities, states, utilities, Equipment Map, eligibility rules, Energy Community data and tax rates are PE's live data. A Test price quote gives the same numbers as a production quote.
    - **Sungage.** Test Sungage calls go to PE's Sungage sandbox account. Production calls go to your company's own Sungage account.
    - **The environments are separate.** A Test key never sees a production project, upload or file. A production key never sees a Test one. The API returns `RESOURCE_NOT_FOUND` for them.

    A production key can carry a scope only after you make at least one successful Test call with that scope. Tell PE when every scope you need works in Test.

    ## Scopes

    | Scope | What it allows |
    |---|---|
    | `avl:read` | Read the Approved Vendor List (AVL), your Safe Harbor opportunities and their custom AVL items, utilities, your active states, your Equipment Map and the reference lists (insurance options, document types, photo categories, project statuses, milestones). |
    | `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. |
    | `pricing:sungage` | List Sungage products and price a Participate Energy lease with a Sungage loan. |
    | `projects:create` | Create projects by uploading signed customer contracts, and read the status of those uploads. |
    | `projects:read` | List and read your projects, their documents, photos, activity, Actions and monitoring access. |
    | `projects:write` | Update project fields, financials, equipment and the Safe Harbor opportunity. |
    | `documents:write` | Upload documents and photos, archive or restore a document version, and save monitoring site IDs. |
    | `actions:write` | Resolve Actions with a note and add notes to Actions. |
    | `webhooks:manage` | Register a webhook endpoint and receive the IC and PC approval events and the new Action events for your projects. |
    | `contracts:write` | Create, read, update, validate and delete Contract Builder drafts that your sales reps finish and send from the Installer Portal. |
    | `contracts:send` | Send a contract draft for e-signature, which creates the project and emails the contract to the homeowner (and cosigner) to sign, and void or re-send a contract. |

    `GET /ping`, `GET /me` and `GET /sandbox/scenarios` need no scope. `POST /sandbox/projects/{projectId}/simulate` needs `projects:read` and a Test key. When a call needs a scope that the key does not carry, the API returns `SCOPE_NOT_GRANTED`.

    ## The actor header

    Send the email of the person who does the work in the `X-PE-Actor-Email` header. This is usually the sales rep or the project coordinator. The header is for attribution. It does not authenticate the call.

    - The header is **required** on every write: contract uploads, `PATCH /projects/{projectId}`, the financials, equipment and Safe Harbor updates, document and photo uploads and their confirm calls, archive and restore, monitoring site saves, and Action resolve and note calls. It is also required on both Sungage endpoints. Without it the API returns `ACTOR_REQUIRED`.
    - 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 your company (or of an organization below your company) in Raceway, or when its domain is one of your company's allowed domains. Otherwise the API returns `ACTOR_NOT_ON_ROSTER`.
    - PE records the email on the change: in the project's activity, in the Action history and as the submitter of a contract.
    - For Sungage, PE sends the email to Sungage as the user who asks for the quote. Sungage must know the email as a user of your Sungage account.

    ## Project ID and external ID

    - **The PE Project ID** (`projectId`, for example `CA2611-SMIT1`) is PE's id for a project. Use it in every project path. A Test project ID starts with `SBX-`.
    - **The external ID** (`externalId`) is your own id for the project, for example your CRM record id. Use 1 to 128 letters, digits, `-` and `_`. Each external ID can belong to one project of your company. Set it when you create the contract upload, or later with `PATCH /projects/{projectId}`.
    - Read a project by external ID with `GET /projects/by-external-id/{externalId}`, or filter the list with `GET /projects?externalId=...`.
    - You can change the external ID on any project that is not Closed, in cancellation or cancelled. This works even after other fields lock.
    - A PE Project ID exists only after a contract upload creates a project. Do not show a PE Project ID to your users before that.

    ## Pricing never creates a project

    A price quote never creates a project and never returns a PE Project ID. The `quoteId` in a pricing response is for your logs only. PE does not store quotes. To create a project, upload the signed customer agreement. See Contract uploads.

    ## Your projects

    A production key reaches every project that your company's portal users can see: the projects of your company and of the organizations below it, from any source (the Installer Portal, this API, the Design API or PE). A Test key reaches only the Test projects that your company created with a Test key. Every other id returns `RESOURCE_NOT_FOUND`, with the same answer whether the id does not exist or belongs to someone else.

    ## The project lifecycle

    A project moves through five milestones. PE sets the milestone from the documents and the approvals. You cannot set it.

    | Milestone | What it means |
    |---|---|
    | `Project Onboarded` | The contract is accepted and the project exists. |
    | `Inspection Complete` | The signed final permit is uploaded. PE reviews the project for IC approval. |
    | `Project Complete` | The Permission to Operate (PTO) letter is uploaded after IC approval. PE reviews the project for PC approval. |
    | `Closed` | PE paid the PC payment. |
    | `Cancellation In Progress` | The project is being cancelled. |

    Install, inspection and PTO are steps that you do. They are not milestones. Approval is separate from the milestone: PE sets the IC approval date and the PC approval date when it approves. The project's `approvals` block shows each approval as `not_started`, `under_review`, `action_required` or `approved`.

    These are the steps and the endpoints for each step:

    | Step | What you do | Endpoints |
    |---|---|---|
    | 1. Before the sale | Read the AVL and reference data. Check eligibility, Domestic Content, Energy Community and sales tax. Price the lease. | `GET /avl`, `GET /reference`, `POST /eligibility`, `POST /checks/*`, `POST /pricing/lease`, `POST /pricing/sungage` |
    | 2. Contract upload | Upload the signed customer agreement. PE reads it and creates the project (Project Onboarded). | `POST /contract-uploads`, `POST /contract-uploads/{uploadId}/submit`, `GET /contract-uploads/{uploadId}` |
    | 3. Documents and photos | Upload the documents and photos for IC. Fix the data and answer the Actions that PE raises. | `GET /projects/{projectId}/documents`, `POST .../documents/{documentType}/uploads`, `POST .../photos/{category}/uploads`, `PUT .../monitoring-access`, `POST .../actions/{actionId}/resolve`, webhook `project.action_created` |
    | 4. Install and inspection | Install the system. Upload the signed final permit. The project moves to Inspection Complete and PE reviews it. | `POST .../documents/signedFinalPermit/uploads` |
    | 5. IC approval | PE approves IC and pays the IC payment. Fields, financials and equipment lock. | Webhook `project.ic_approved` |
    | 6. PTO | Upload the PTO letter and the other PC documents. The project moves to Project Complete and PE reviews it. | `POST .../documents/permissionToOperate/uploads` |
    | 7. PC approval | PE approves PC and pays the PC payment. | Webhook `project.pc_approved` |

    Use `PATCH`, `PUT .../financials`, `PUT .../equipment` and `PUT .../safe-harbor` while the project is in its edit window. See Editing rules.

    ## How PE prices a lease

    PE's main product is the prepaid lease (Synthetic Cash). The customer pays the Net Amount Due to you. PE pays you the PE payout in two milestone payments. `POST /pricing/lease` runs the same calculation as the Lease Value Calculator in the Installer Portal. Each step below names the response field in brackets.

    **1. The EPC.** `epcAmount` is your price for the system before tax, in USD. Include any sales or use tax that you pay on equipment. Do not include the lease sales tax. PE adds that tax in step 8.

    **2. Insurance.** The customer selects one of three homeowner's insurance options. `GET /reference` lists them with the full text.

    | 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. You complete the Homeowners Insurance Rider and upload it as the Insurance Supporting Document. Use this option only when options 1 and 2 were tried in good faith and are not possible. | 2.5% of the EPC |

    Option 3 has two effects. 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 IC 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 of the roof under the solar array. It joins the EPC basis and gets the lease discount.
    - Ineligible roofing (`ineligibleRoofingCost`) is the rest of the roofing work. The customer pays it at full cost, with no discount.
    - For example, a $40,000 re-roof where 25% of the re-roofed area is under the array has $10,000 eligible and $30,000 ineligible roofing.
    - Keep the roof assessment, the area measurements and the cost split in the project files. PE expects conservative and defensible percentages.

    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% | Neither PV nor storage Domestic Content (as applies to the system type) and no Energy Community. |

    - **Domestic Content** applies only when every component of a type qualifies. The threshold depends on the year that construction begins: 45% in 2025, 50% in 2026, 55% from 2027. A Safe Harbor beginning of construction date sets the year. Use `POST /checks/domestic-content` to check your equipment.
    - **Energy Community** alone does not raise the factor above the baseline. It prevents the 25% tier. Use `POST /checks/energy-community`, or send `energyCommunity: "auto"` in the quote.
    - PE confirms the Domestic Content and Energy Community bonuses at PTO. 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 you the difference [`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`].

    **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 you, before lease sales tax.

    Included incentives (`includedIncentive`): `hawaii_retitc` is the Hawaii Renewable Energy Technologies Income Tax Credit, 5% of the EPC, for Hawaii contracts dated before 2026-07-03. The API does not accept a Hawaii `contractDate` before 2026-07-03 (`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`), so it prices no RETITC. It is part of the PE payout. `installer_managed` is a state incentive that you collect, for example from NYSERDA in New York. Send its amount. 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 you bear 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 rate from the site address [`salesTax`]. PE collects lease sales tax only where its 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, so send `existingSolarOnProperty` for a `battery_only` system. You collect the tax from the customer on top of the Net Amount Due and show it in the customer agreement. PE remits the tax and deducts it 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. Use `POST /checks/sales-tax` to read the rate for an address.

    **9. The payments.**

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

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

    ### Price from the EPC or from the Net Amount Due

    `POST /pricing/lease` and `PUT /projects/{projectId}/financials` take a `basis`:

    - `epc` (the default for pricing): send `epcAmount`. PE computes the chain forward to the Net Amount Due.
    - `netAmountDue`: send `targetNetAmountDue` and no `epcAmount`. PE solves the EPC that gives this Net Amount Due with the same inputs, rounds it to cents, and prices it. The solved EPC prices back to the target within $0.01. Use this basis when your sales process starts from the customer's price.

    The response gives `basis`, `epcAmount` (the EPC sent or solved) and `targetNetAmountDue`.

    ### The pricing chain on a project

    `GET /projects/{projectId}` returns the stored chain in `financials`:

    | Field | Meaning |
    |---|---|
    | `epcAmount` | The EPC. |
    | `eligibleRoofingCost`, `ineligibleRoofingCost` | The roofing split. |
    | `adjustedEpcAmount` | EPC + insurance adjustment + eligible roofing. |
    | `replacementCost` | The replacement cost of the system. |
    | `leaseFactor` | The lease factor of the project. |
    | `discountedAmount` | Adjusted EPC - lease discount. |
    | `baselineLeaseAmount` | The lease amount before included incentives. |
    | `stateIncentive`, `utilityIncentive` | Included incentives. |
    | `netAmountDue` | What the customer pays, before lease sales tax. |
    | `pePayout` | What PE pays you in total. |
    | `icPayment`, `pcPayment` | The milestone payments. |
    | `insuranceOption`, `insuranceRiskAdjustment` | The insurance option (`"1"`, `"2"` or `"3"`) and its adjustment. |
    | `salesTaxRate`, `salesTaxAmount` | The lease sales tax. |
    | `dcBonusRecipient` | `Installer` or `Customer`. |
    | `lender`, `amountFinanced` | The customer's lender, if any, and whether the lender finances the amount. |

    The pricing endpoints and the project financials use two spellings for two fields. Pricing takes `insuranceOption` as a number (`1`, `2`, `3`) and `dcBonusRecipient` as `installer` or `customer`. The project financials take and return `insuranceOption` as a string (`"1"`, `"2"`, `"3"`) and `dcBonusRecipient` as `Installer` or `Customer`.

    ### Safe Harbor

    A Safe Harbor opportunity lets a project use PE Safe Harbor equipment. `GET /safe-harbor/opportunities` lists your company's opportunities with the units available. `GET /safe-harbor/opportunities/{opportunityId}` adds the opportunity's custom AVL: equipment that counts for Domestic Content under that opportunity. PE manages the custom AVL. Link a project to an opportunity with `PUT /projects/{projectId}/safe-harbor`. The project uses the units at IC approval. After that, you cannot unlink it. Request Safe Harbor equipment from PE at SafeHarborRequest@participate.energy.

    ### Sungage

    PE and Sungage offer a PE lease with a Sungage loan for the customer's prepayment. Your company must be in the PE and Sungage program, and PE must have your Sungage account on file. Read the products, terms and rates for a state with `GET /pricing/sungage/products`. Then price one combination with `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. The amounts are estimates. Sungage sets the final terms.

    ## Editing rules

    You can edit a project in its edit window. The `editability` block of `GET /projects/{projectId}` tells you the state of the project now.

    - **The edit window.** The milestone is `Project Onboarded`, or it is `Inspection Complete` and PE has not yet approved every document (the review status is not `Approved`). IC approval closes the window. Outside the window, field changes return `PROJECT_LOCKED` with the reason.
    - **IC approval locks the values.** After PE approves IC, you cannot change fields, financials or equipment through the API. A financials or equipment change returns `CHANGE_ORDER_REQUIRED`. A change now needs a signed change order. Upload it as the `changeOrder` document, or contact PE.
    - **Change orders before IC approval.** Some changes need a change order even inside the edit window. Examples: a customer name change that is more than a spelling fix, a change of the Net Amount Due, and a system size or battery size outside -3% to +10% of the contract. PE saves the change and creates change order Actions. The response then has `changeOrder.required: true` and the `actionIds`. A change that needs a PE review returns `CHANGE_ORDER_BLOCKED`.
    - **Re-signature.** When you change the customer's first name, last name or email, or the cosigner's name, the response has `resignRequired: true`. The customer must sign the agreement again.
    - **Fields you cannot clear.** Names, email, phone, address, utility, sales rep, system size and EPC cannot be cleared once they are set.
    - **Distributed Microgrid projects.** PE sets their financials, and Safe Harbor does not apply to them. `PUT .../financials` returns `FINANCIALS_SET_BY_PE` and `PUT .../safe-harbor` returns `SAFE_HARBOR_NOT_FOR_DM`, as the Installer Portal shows them read-only.
    - **Fields you cannot change.** The system type, the contract type, the contract signed date, the PTO date and the PE payout outputs. PE computes the outputs. The PTO date comes from the PTO letter: a PATCH with `ptoDate` returns `FIELD_NOT_EDITABLE`.
    - **External ID.** You can change it on any project that is not Closed, in cancellation or cancelled.
    - **Dry runs.** `PATCH /projects/{projectId}`, `PUT .../financials` and `PUT .../equipment` take `?dryRun=true`. A dry run checks the change and returns the result without a write.
    - **Concurrency.** Send `expectedUpdatedAt` with the `updatedAt` you read. If the project changed after that time, the API returns `PROJECT_CHANGED_SINCE_READ`. Read the project again and resend.
    - **Cancelled projects.** A cancelled project can be read but not changed (`PROJECT_CANCELLED`).

    ## Documents

    `GET /projects/{projectId}/documents` lists every document slot that applies to the project, the same list as the Required Documents checklist in the Installer Portal. PE works out the list from the project's facts, so do not hard-code it.

    - **Required at IC.** The base set is: Customer Agreement, Utility Bill, Signed Proposal, Design Plan, Photos per Policy, Signed Final Permit, Access to Monitoring, Certificate of Acceptance, Attestation of Customer Payment and Conditional Progress Lien Waiver. State Disclosures apply to California projects with a utility that the CPUC regulates.
    - **Required at PC.** Signed Interconnection Agreement, Conditional Waiver and Release on Final Payment, and Permission to Operate.
    - **Conditional slots.** Bill of Sale (contracts that you originate), Load Justification Form (solar offset above 135%), Roofing Cover Letter (roofing cost above 0), Insurance Supporting Document (insurance option 3), Change Order (optional, never blocks), and Safe Harbor documents (projects linked to an opportunity). Some slots are required but do not block review yet. The slot's `blocking` field tells you.
    - **Stage.** `stage` is `ic` or `pc`. You can upload PC documents while the project is at Inspection Complete.
    - **Upload locks.** An IC-stage slot accepts uploads until PE approves IC. A PC-stage slot accepts uploads until PE approves PC. Closed and cancelled projects accept no uploads. `uploadOpen` and `uploadClosedReason` tell you the state of each slot.
    - **Versions.** A new upload never overwrites a file. It adds a version. You must archive every version that is not valid: a wrong file, a file for a different project, or an older file that a newer version replaces. SIBYL reviews every version that is not archived. An invalid version that stays active can cause review errors and Actions on the project. You can restore an archived version. PE never deletes a version.
    - **Files.** A document can be PDF, JPEG, PNG, HEIC or HEIF, up to 50 MB. PE prefers PDF.

    ### The upload flow

    1. **Create the upload.** `POST /projects/{projectId}/documents/{documentType}/uploads` with `fileName` and `contentType`. The response has `fileUploadId`, a signed `uploadUrl` and `uploadHeaders`. The URL is valid for 15 minutes.
    2. **Put the file.** Send the 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`. Do not send an Authorization header. The URL accepts one file only.
    3. **Confirm.** `POST .../uploads/{fileUploadId}/confirm`. PE checks the size and the file signature (the first bytes must match `contentType`), adds the version and starts the review. You can add `notes` and `resolveActionIds` (the Actions this file answers). A repeated confirm returns the same version, so it is safe to retry. When the first confirm saved the file but you lost its answer, the retry returns the existing version with `reviewQueued: false`; the review of that version is already queued.

    ### Review statuses

    Each slot has a `reviewStatus`:

    | Status | Meaning |
    |---|---|
    | `Response Needed` | The slot has open Actions. You must act. |
    | `Pending Review` or `Pending Approval` | The file waits for a PE reviewer. |
    | `Under Review` | PE is reviewing the file. |
    | `Approved` | PE approved the slot. An approval stays when Actions close later. |

    The project's `documentReviewStatus` rolls the slots up: `Action Required (Installer)` when a required document is missing or a slot needs a response, `Under Review (PE)` while PE reviews, and `Approved`.

    ### Automated review (SIBYL)

    PE's automated document review (SIBYL) reads many document types after upload. It checks the file against PE's rules and the project data. The confirm response says `reviewQueued: true` when a review started.

    - Each finding becomes an Action on the slot. A `fail` Action blocks the slot. A `warn` Action is advisory.
    - `sibyl.state` on a slot shows the result for the current file: `processing` (the review runs), `clean` (no findings), `warn` (advisory findings only), `gray` (a PE reviewer must decide), or `null` (no automated result for the current file, or an open `fail` Action carries the finding).
    - When a new upload no longer shows a finding, PE resolves its Action. An Action that a person closed is not raised again for the same file version.
    - The Customer Agreement, State Disclosures and the Installation Order are reviewed together as one contract packet.
    - PE's review takes 3 to 5 business days as a guide. There is no fixed time.

    ## Photos

    Photos are one deliverable, "Photos per Policy", with one review status. Upload them by category.

    | Category | Label | What it shows | Solar only | Solar and battery | Battery only |
    |---|---|---|---|---|---|
    | `site_address` | Site Address | Site address with the home in the background. | yes | yes | yes |
    | `pv_array_wide` | PV Array Wide Angle | Wide angle of the photovoltaic (PV) array with all modules installed. | yes | yes | no |
    | `module_nameplate` | Module Nameplate | Close-up of one module nameplate label. Must clearly show manufacturer name, model number, serial number, electrical ratings, country of origin, and certification. | yes | yes | no |
    | `electrical_equipment_wide` | Electrical Equipment Wide Angle | Wide angle of all electrical equipment, indoor and outdoor, PV and storage together if possible. | yes | yes | no |
    | `main_service_panel` | Main Service Panel | Main service panel with the cover off and breakers visible. | yes | yes | no |
    | `invoice_bom` | Invoice and Bill of Materials | Must show the project name and/or address, domestic content part numbers listed on PE's AVL, and parts that correspond with the install photos. | yes | yes | yes |
    | `inverter_model` | Inverter Model | Clearly legible model number for the inverter, microinverters, or optimizers used on site. | yes | yes | no |
    | `racking` | Racking | Photos of the racking parts, packaging, and part markings. | yes | yes | no |
    | `storage_wide` | Storage Wide Angle | Wide angle of storage showing the bracket and enclosure. | no | yes | yes |
    | `storage_nameplate` | Storage Nameplate Labels | Close-up of each storage unit's nameplate and compliance labels. Must show manufacturer name, model number, serial number, electrical specs, and country of origin. | no | yes | yes |
    | `storage_controller` | Storage Controller and Disconnect | Storage controller and disconnect, wide angle with the serial number visible and wiring, in a single clear shot. | no | yes | yes |

    - Every category for the project's system type needs at least one file before the photos go to review. `GET /projects/{projectId}/photos` shows the files per category and `sectionsMissing`.
    - `POST /projects/{projectId}/photos/{category}/uploads` takes 1 to 25 files. Each file gets its own upload URL. Then confirm the batch with `POST .../uploads/{batchId}/confirm`.
    - A photo can be JPEG, PNG, HEIC, HEIF, WebP, GIF or PDF, up to 100 MB.
    - Photos must match the project data, the plan set and the permit. Equipment can change within -3% to +10% of the system size. When a photo is missing, explain why in the confirm `notes`.
    - Photos uploaded before categories existed are in the category `uncategorized` (Legacy Photos). They do not count toward coverage.

    ## Monitoring access

    PE owns the system and needs access to it in the manufacturer's monitoring portal. Add PE in each portal first:

    | Provider | What to do in the portal | Site ID format |
    |---|---|---|
    | `tesla` | Add Participate.Energy LLC as Partner with the relationship Owner. | The Powerhub site UUID, or the STE site name such as `STE20240115-01234`. |
    | `enphase` | Mark the system Third Party Owned with owner email channel@participate.energy. Never mark it Cash Purchase. | The numeric system ID. |
    | `solaredge` | Add the account solaredge@participate.energy as Site Owner. | The numeric site ID. |
    | `lunar` | Lunar links the organization first. Then add the site to the PE group. | The site token, with no spaces. |
    | `qcells` | Add the company. | Any text up to 100 characters. PE reviews it by hand. |
    | `other` | Follow PE's instructions for the manufacturer. | Any text up to 100 characters. |

    - Save the site IDs with `PUT /projects/{projectId}/monitoring-access`. Send all the sites each time (up to 10). Send `verify: "now"` (the default) to start the check at once.
    - PE checks each site: the site ID is not used on another project, PE can reach the site, PE is the owner where the provider can show it, and the equipment matches the project. The result is in `GET /projects/{projectId}/monitoring-access`.
    - The required providers come from the project's inverter and battery manufacturers. A Tesla battery with an Enphase inverter needs two sites.
    - Send `baseSitesHash` from your last read to avoid overwriting a change made by someone else.
    - After IC approval, the sites are read-only.
    - In the Test environment PE does not contact the manufacturers. A save records the sites and marks the check as pending.

    ## Actions

    An Action is one issue on a project that you must answer. It usually belongs to one document slot. PE's automated review, PE reviewers and PE's data checks create Actions. You cannot create or delete them.

    - `severity` is `fail` (it blocks the slot) or `warn` (advisory).
    - `status` is `open`, `resolved`, `reject`, `ai_error` or `cannot_resolve`.
    - Answer an Action in one of three ways: upload a corrected file (PE resolves the Action when the finding is gone), fix the project data, or resolve it with a note (`POST .../actions/{actionId}/resolve`). Every resolve needs a note. Notes cannot be changed or deleted.
    - Add a note without a status change with `POST .../actions/{actionId}/notes`.
    - An open `fail` Action puts its slot in `Response Needed` and the project in `Action Required (Installer)`.
    - After IC approval, a new Action does not undo IC. It blocks PC approval.

    ## Webhooks

    PE calls your URL when PE approves IC or PC on one of your projects, when PE creates an Action on one of your projects, and when the e-sign status of a project's contract changes.

    ### Set up

    1. Call `PUT /webhooks` with an https URL. PE checks that the host resolves to public addresses only.
    2. Keep the `signingSecret` from the response. PE shows it only in this response and after a rotation.
    3. Call `POST /webhooks/test`. PE sends a `webhook.test` event and returns the result of the delivery.

    Each environment has its own URL and secret. Test keys set the Test URL. Production keys set the production URL. A new URL receives only approvals, Actions and contract changes that happen after you set it. PE does not send past events. To change the URL, call `PUT /webhooks` again: the secret stays the same and no events are lost. Rotate the secret with `POST /webhooks/rotate-secret`. PE signs each delivery with the secret that is current when PE sends it.

    ### Events

    | Type | When |
    |---|---|
    | `project.ic_approved` | PE approved Inspection Complete. `data.approval.approvedAt` is the date. |
    | `project.pc_approved` | PE approved Project Complete. `data.approval.approvedAt` is the date. |
    | `project.action_created` | PE created an Action on the project. `data.action` is the Action, the same object that `GET /projects/{projectId}/actions` returns. |
    | `project.contract_status_changed` | The contract of the project changed: it was sent, viewed, signed by a signer, completed, declined, voided, expired or cancelled. `data` has `packetId`, `status`, `signers` (`role`, `status`, `signedAt`) and `occurredAt`. See Contract drafts and e-sign. |
    | `webhook.test` | You called `POST /webhooks/test`. `data` is empty. |

    Ignore event types that you do not handle. PE can add event types in a minor version.

    PE checks for new approvals, contract changes and new Actions every 5 minutes, so an event can arrive some minutes after the change. PE sends a `POST` with a JSON body and these headers:

    | Header | Value |
    |---|---|
    | `PE-Event-Id` | The event id (`evt_...`). It is the same on every retry. |
    | `PE-Event-Type` | The event type. |
    | `PE-Signature` | `t=<unix seconds>,v1=<hex signature>` |
    | `User-Agent` | `ParticipateEnergy-Webhooks/2` |
    | `Content-Type` | `application/json` |

    The body:

    ```json
    {
      "id": "evt_3f9a1c2b7d4e5f60718293a4",
      "type": "project.ic_approved",
      "createdAt": "2026-11-11T18:05:00.000Z",
      "environment": "live",
      "data": {
        "projectId": "CA2611-SMIT1",
        "externalId": "crm-10442",
        "approval": {"stage": "ic", "approvedAt": "2026-11-11"}
      }
    }
    ```

    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. An approval event comes at most once for each project. A `project.action_created` event comes at most once for each Action. A `project.contract_status_changed` event comes once for each new state of a contract (its status and the status of each signer). When several events are due at once, PE sends the approvals first, then the contract events, then the Action events. A retry can still arrive after a success that timed out, so use `PE-Event-Id` to ignore repeats. Webhooks do not replace reads: read the project when you need its current state.

    ### Verify the signature

    The signature is the hex HMAC-SHA256 of `<t>.<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-Event-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", ""))
    ```

    ## Contract uploads

    Create a project from the signed customer agreement. In production, PE reads the contract and creates the project, or saves a draft in the Installer Portal. In the Test environment, PE simulates the result.

    1. **Create the upload.** `POST /contract-uploads` with `X-PE-Actor-Email`, the `stateCode` and the `fileName`. Add your `externalId` and the `salesRep` when you have them. The response has `uploadId`, a signed `uploadUrl`, `uploadHeaders` and `expiresAt`. 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`. Do not send an Authorization header. The limit is 25 MB. The URL accepts one file only: a second `PUT` gets HTTP 412.
    3. **Submit.** `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. If the submit fails with a 5xx error, send it again.
    4. **Poll.** Read `GET /contract-uploads/{uploadId}` until `status` is `project_created`, `needs_attention` 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. An upload with no result 2 hours after the submit ends as `failed` with the outcome `processing_failed`. An upload cancelled in the Installer Portal ends as `failed` with the outcome `cancelled`.
    5. **Act on the outcome.** Show `outcomeMessage` to your user. When `status` is `project_created`, `projectId` is the PE Project ID. Follow the project with `GET /projects/{projectId}` and webhooks.

    Rules:

    - PE checks your company before it creates the upload: it is an install partner, it is not on hold, it is active in `stateCode`, and Synthetic Cash is enabled.
    - The API creates Synthetic Cash projects only. Leave `productType` out or send `Synthetic Cash`. Upload Distributed Microgrid contracts in the Installer Portal; the API answers `PRODUCT_NOT_SUPPORTED_BY_API`. `GET /me` lists the products in `apiContractUploadProducts`.
    - An `externalId` can be on one open upload or project of your company. When an upload ends with no project (`needs_attention` or `failed`), or its URL expires with no file, PE releases its `externalId` and you can use it again.
    - A draft is not a project. You finish a draft in the Installer Portal. When you create the project from the draft, the upload shows `project_created` and the `projectId`.

    ### Upload statuses

    | 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. |
    | `project_created` | PE created the project. Read `projectId`. |
    | `needs_attention` | No project was created. The contract is a draft in the Installer Portal, or it needs a new upload. Read `outcome`. |
    | `failed` | No project was created. Read `outcome`. |

    ### Outcomes

    | Outcome | Status | Message |
    |---|---|---|
    | `project_created` | `project_created` | Participate Energy read the contract and created the project. Read it with GET /v2/installer/projects/{projectId} and follow its Actions and approvals. |
    | `draft_failed_basic_tests` | `needs_attention` | The contract was read, but it did not pass the basic checks, so it was saved as a draft in the Installer Portal and no project was created. The failed checks are in errors. Fix them in the Installer Portal draft, or upload a corrected contract. |
    | `draft_invalid_document` | `needs_attention` | The file does not look like a Participate Energy customer agreement, so no project was created. Upload the signed Participate Energy customer agreement. |
    | `draft_duplicate` | `needs_attention` | The contract matches a project that already exists for this installer, so it was saved as a draft in the Installer Portal and no project was created. If it is a new project, create it from the draft in the Installer Portal. |
    | `draft_manual_entry` | `needs_attention` | The contract could not be read automatically, so it was saved as a draft in the Installer Portal. Enter the missing details there to create the project. |
    | `product_mismatch` | `needs_attention` | The contract is for a different Participate Energy product than the productType of the upload, so no project was created. Create a new upload with the right productType. |
    | `canon_rejected` | `failed` | The contract was read, but its data did not pass Participate Energy's project checks, so no project was created. Review the upload in the Installer Portal, or contact raceway.support@participate.energy with the uploadId. |
    | `sibyl_error` | `failed` | Participate Energy could not finish reading the contract because of a processing error, so no project was created. Create a new upload, or retry the upload in the Installer Portal. |
    | `cancelled` | `failed` | The upload was cancelled before a project was created. Create a new upload if the contract should still become a project. |
    | `processing_failed` | `failed` | Participate Energy did not finish processing the contract, so no project was created and the externalId was released. Create a new upload to try again; you can use the same externalId. If it fails again, contact raceway.support@participate.energy with the uploadId {uploadId}. |
    | `upload_expired` | `failed` | The upload URL expired before a file arrived, so the upload was closed and its externalId was released. Create a new upload with POST /v2/installer/contract-uploads. |
    | `file_rejected` | `failed` | The uploaded file was not a PDF or was larger than 25 MB, so the upload was closed and its externalId was released. Create a new upload for the signed customer agreement as a PDF. |

    `errors` lists the failed checks of the review, in the words you see in the Installer Portal. `actions` lists the open Actions of a new project, in the same shape as `GET /projects/{projectId}/actions`.

    ## Contract drafts and e-sign

    <a id="contract-drafts"></a>

    A contract draft is a Contract Builder draft that your software fills in for one of your sales reps. Your software sends it for e-signature, or the rep opens it in the Installer Portal (Contract Builder, Drafts tab), checks it and sends it from there. Scopes: `contracts:write` for drafts, `contracts:send` to send, send again and void. Keys issued before 2.2 do not carry the new scopes; ask PE to add them.

    ### Prefill or send

    - **Prefill**: create a draft with `POST /contract-drafts`, fix what `validation.issues` lists with `PATCH /contract-drafts/{draftId}`, and give the rep the `portalUrl`. The rep sends the contract from the portal.
    - **Send through the API** (`contracts:send`): when `validation.readyToSend` is `true`, `POST /contract-drafts/{draftId}/send` creates the project and emails the contract to the homeowner, the same outcome as Send on the portal's Review step. See Send a draft for e-signature.

    ### The rep who owns a draft

    Every draft belongs to one rep: an active Installer Portal user of your company whose role can create projects (administrator, editor or operations). Send the rep's email in `assignedToEmail`. Without it, the draft goes to the user in the `X-PE-Actor-Email` header, which the create, update and delete calls require. The draft shows in that rep's Drafts tab only. An email that is not an active user of your company returns `ASSIGNEE_NOT_FOUND`; a user whose role cannot create projects returns `ASSIGNEE_NOT_PERMITTED`. A `PATCH` keeps the rep unless you send another `assignedToEmail`. Empty sales rep fields are filled from the rep's portal profile, as the portal does.

    ### Your prefill: defaults, locks and equipment limits

    A draft starts from your company's prefill for the site's state (Installer Portal, Prefills; the state settings, else the global ones), exactly as a draft started in the portal: payment milestones and their percentages, the forecasted install and PTO dates (days after the contract date), the lender, payment instructions, the DC bonus recipient, the energy savings calculator, additional products and incentives. A value you send replaces a prefilled default. The draft's `prefilledFields` lists the body fields that still hold a prefilled value.

    - **Locks.** When your prefill locks the payment instructions or the DC bonus recipient, a different value returns `PREFILL_LOCKED_FIELD`. Leave the field out, or send the locked value.
    - **Equipment limits.** An AVL item your prefill excludes for the state returns `EQUIPMENT_NOT_ALLOWED_BY_PREFILL`. Your prefill excludes items by name, so an exclusion covers every AVL item with that name: `equipmentLimits` in the defaults lists an excluded name once per AVL item id. A line sent by `name` uses an item your prefill allows when the name matches one; when it matches several allowed items, the answer is `EQUIPMENT_AMBIGUOUS` with only those candidates.
    - `GET /contract-drafts/defaults?stateCode=CA` returns the defaults, the locks, the excluded equipment, the included incentives of the state and the state's contract fields, so you can build your own form from it. Add `utility` (the name you will send as `utility.name`) to list only the included incentives that apply to that utility. Without it every included incentive of the state is listed, each with its `requiresUtility` (the utility names it applies to, or `null`) and `requiresStorage`, and `utility` and `utilityRecognized` in the response are `null`. `utility` takes any name `GET /utilities` returns for a ZIP code of the state, or the utility's EIA name; the response's `utility` is the name the Contract Builder stores (for example `Sacramento Municipal Util Dist` for `SMUD (Sacramento Municipal Utility District)`). A name that is not in PE's utility list gives `utility: null` and `utilityRecognized: false`, and the list is filtered as a draft treats it, with no utility. A draft carries up to two included incentives with empty amounts: first the ones your company's prefill names (`defaults.includedIncentives`), and when the prefill names none, the applicable ones for the utility from `includedIncentivesForState`. A prefill incentive that is not offered for the draft's state, system type, utility and contract date is left out of the draft, and the draft gets a `PREFILL_INCENTIVE_NOT_APPLICABLE` warning that names it (`incentiveId`; `field` is `financials.includedIncentives` or `financials.incentives`) and says why (`reason`); when none of the prefill's included incentives is offered, the applicable ones are used. The warning never stops the draft. Two reasons are prefill errors, and the message asks your administrator to fix the prefill for that state: `not_offered_in_state` (for example a New York incentive in a global prefill, on a California draft) and `wrong_incentive_list` (an additional incentive named as included, or the reverse). The other three are expected for a correct prefill, and the message says no change is needed: `system_type` (a storage incentive on a Solar Only draft), `utility` (an incentive for another utility than the draft's) and `contract_date` (the Hawaii RETITC, included only for contracts dated before 2026-07-03). `defaults.includedIncentives` and `defaults.incentives` list only the prefill incentives the state offers, with the utility when you send it. They assume a PV+Storage system and today's contract date, and no utility filter unless you send `utility`, so a draft can still leave one of them out for its own system type, utility or contract date (with the warning above). Send the `amount` of each in `financials.includedIncentives` (`DRAFT_FIELD_REQUIRED` names the incentive and carries its `incentiveId`). Outside New York send `0`: the API prices a non-zero included amount only in New York. Each state field in `stateFields` has `requiredForSystemTypes`: the system types a required field is asked for (`null` for all of them). `stateSpecificFields` lists the body fields outside `stateFields` that only this state's contract has (New York: `sales.nyLicenseNumber`).

    ### The draft body

    Every field is optional except `siteAddress.stateCode` on create. A draft can be incomplete: what is missing comes back in `validation.issues`. Units: system sizes in kW DC, module, inverter and battery power in W, usage and production in kWh per year, money in USD totals, dates as YYYY-MM-DD.

    | Field | What it holds |
    |---|---|
    | `assignedToEmail` | The rep who owns the draft (see above). |
    | `externalId` | Your id for the deal (letters, digits, `-` and `_`, at most 128). Filter the list with it. It is unique: when another open draft or a project of your company (same environment) has it, the create (dry runs too) or a `PATCH` that changes it returns `EXTERNAL_ID_IN_USE` (409), and `details` names the holder (`heldBy` `draft` with its `draftId`, or `project`). This is a check before the draft is saved, not a lock: two requests at the same moment can both pass it, and the send is the authoritative check (it creates the project in a transaction and refuses an `externalId` another project has). |
    | `label` | The name in the Drafts tab. Default: "First Last (City, ST)". |
    | `customer` | `firstName`, `lastName` (one line, no control characters), `email`, `phone` (10 digits, or 11 digits starting with 1). |
    | `cosigner` | Optional second homeowner: `firstName`, `lastName`, `email` (must differ from the customer's), `phone` (the customer's rule). `null` removes it. The state's agreement must have a cosigner signature (`contractTemplate.cosignerAllowed` in `GET /contract-drafts/defaults`), else the draft has the issue `COSIGNER_NOT_SUPPORTED`. |
    | `siteAddress` | `street` (no PO Box), `unit`, `city`, `stateCode`, `zipCode` (5 digits or ZIP+4, not 00000), `county`. A ZIP code that PE's ZIP list puts in another state is the warning `ZIP_CODE_NOT_IN_STATE`. It does not block the send: the list has one state per ZIP code and can be wrong near a state line. The lease pricing address check (`STATE_MISMATCH`) is the check that refuses a site outside the state. |
    | `mailingAddress` | Only when it differs from the site: `street`, `city`, `stateCode`, `zipCode`. `null` means same as the site. |
    | `utility` | `name` (a utility of the state: a name `GET /utilities?zipCode=` returns for the site ZIP code, or the utility's EIA name; the draft stores the name the Contract Builder uses for it) and `nameOnBill` when the bill is not in the customer's name. A name PE does not recognize is the issue `UTILITY_NOT_RECOGNIZED`, which names the utilities of the site ZIP code (when PE's ZIP list puts the site ZIP code in another state, the message says so instead); a utility that the site ZIP code does not list is the warning `UTILITY_NOT_SERVING_ZIP`. |
    | `product` | `productType`: `Synthetic Cash` (the default). `Distributed Microgrid` returns `PRODUCT_NOT_SUPPORTED_BY_API`. |
    | `system` | `systemType` (`Solar Only`, `PV+Storage`, `Storage Only`; `solar_only`, `solar_battery` and `battery_only` also work), `annualUsageKwh`, `annualProductionKwh`, `energySavingsCalculator`, `existingSolarOnProperty`, `energyCommunity` (`true`, `false` or `"auto"`, the default: PE runs the Energy Community check), `systemSizeKw` (optional check: kW DC from 0.5 to 250, within 25% of modules x watts, or 250 W to 1,000 W per module when the wattage is not known; the draft's PV size is always modules x watts / 1000, see Lease pricing on a draft) and `confirmManufacturerMismatch` (confirms an inverter and battery from different manufacturers). |
    | `equipment` | Up to one line per `category`: `module`, `acModule`, `inverter`, `racking`, `battery`. Each line has `avlItemId` or `name`, and `quantity`. `wattsDc` (module) is needed when the AVL item has no wattage (a model name with "xx"); when it has one, leave `wattsDc` out or send the same wattage (another value returns `VALIDATION_FAILED`). `acWatts` (inverter) and `outputPowerW` (battery on Storage Only) override the AVL values. PV System Size is modules x watts / 1000. Battery Output Power is the battery's continuous power on the AVL times the battery quantity, blank when the AVL does not have it; on Storage Only it is the `outputPowerW` you send. A PV+Storage or Storage Only system needs a `battery` line; a Solar Only system has none. |
    | `financials` | Money in USD with at most 2 decimals. `epcAmount` (1,000 to 500,000 USD), `dcBonusRecipient` (`installer` or `customer`), `lender` (`{financed, name}`; `name` is needed when `financed` is true), `paymentInstructions`, `addersAndUpgrades`, `additionalProducts` (`[{slug, amount, coveragePercent}]`, the complete list; `coveragePercent` for `full-reroof` only), `includedIncentives` (`[{id, amount}]`, up to 2; the amount must be 0 outside New York, where a non-zero included amount is the only one the API prices), `incentives` (`[{id, amount}]`, up to 4) and `payments` (`[{name, amount}]`, up to 4; Payment 1 is always "Deposit/Due at signing", so leave its name out). |
    | `sales` | `salesRepName`, `salesRepEmail`, `salesRepPhone`, `salesRepLicense`, `nyLicenseNumber` (New York), `contractDate` (default today; a Hawaii date must be on or after 2026-07-03), `installStartDate` (on or after the contract date), `ptoDate` (after the install start). The agreement of some states needs `salesRepLicense` (`contractTemplate.requiredFields`). |
    | `stateFields` | The state's contract fields by key, for example `utilityBillsUsed`, `preSolarTariff` and `estimatedSavingsMaxBill` in California. `GET /contract-drafts/defaults` lists them with their types, `min` and `max` (a number or currency field without its own minimum takes 0 or more), `zeroAllowed` and whether they are `required`, by the builder or by the state's agreement. `coQtyOfPayments` and `ncQtyOfPayments` take a whole number from 1 to 4, `coMonthlyFixedUtilityCharges` a dollar amount of 0 or more with at most 2 decimals (kept with exactly 2, for example `7.10`), `coUtilityRateEscalator` and `txUtilityRateEscalator` 0 to 100, as a number or numeric text without the $ or %, which the agreement prints. A 0 counts as a value only where `zeroAllowed` is `true`. Where it is `false` (a number or currency field without a declared minimum, such as `estimatedSavingsMaxBill` or `bondAmount`, and `ncPeguYear1Output`), a 0 is read as not sent although `min` is 0, so a required field stays `DRAFT_FIELD_REQUIRED`; a field whose `min` is above 0 refuses a 0 (`VALIDATION_FAILED`). A key that is not a field of the state returns `VALIDATION_FAILED` naming the key, with `didYouMean` when one is close. A `null` clears a field, on create and on `PATCH` alike: the field is blank (never its form default, such as `coMountType` Roof Mount), so a required one is `DRAFT_FIELD_REQUIRED`. A key the draft already holds that is not a field of its state (for example after a change of `siteAddress.stateCode`) is kept but not used, and never blocks a `PATCH`; only a key the request itself sends is checked. In California on Solar Only, the draft sets `estimatedSavingsSolarOnly` to `estimatedSavingsMaxBill` (the Contract Builder's rule), so send `estimatedSavingsMaxBill` only: a different value you send is replaced, and `warnings` has `STATE_FIELD_REPLACED`. |

    ### Lease pricing on a draft

    When the pricing inputs are complete (EPC, system type, site address, DC bonus recipient and the equipment), PE prices the lease with the same calculation as `POST /pricing/lease` and stores it on the draft, so the portal shows a current price and the rep does not have to calculate again. `pricing` has the same fields as the `/pricing/lease` response. Domestic Content comes from the equipment you chose, roofing from the additional products, and the insurance option is 1. The payment amounts come from your prefill's milestone percentages unless you send `payments`. A value outside the pricing guardrails (EPC range, kW in watts, PO Box, contract date window) is refused like on `/pricing/lease`.

    Two size ranges apply. A `system.systemSizeKw` you send must be from 0.5 to 250 kW DC (the pricing guardrail, `SYSTEM_SIZE_OUT_OF_RANGE` or `SYSTEM_SIZE_LOOKS_LIKE_WATTS`) and within 25% of modules x watts (`SYSTEM_SIZE_MISMATCH`). The draft's PV system size is always modules x watts / 1000, and the Contract Builder takes it within the PV System Size range of the state's builder, 1.2 to 50 kW DC by default: outside it, the draft has the issue `SYSTEM_SIZE_OUT_OF_RANGE`, which names the module size, the modules and the size you sent. System Size AC (the inverters' AC watts times their quantity) is at most 50 kW. An included incentive amount outside New York is not priced by the API: the issue says so and the rep prices it in the portal.

    ### Validate, fix, then send

    `validation.readyToSend` is `true` when the draft passes every check the Contract Builder runs before it sends, and the checks the send runs on the state's customer agreement: the agreement is published for the state, it has a place for the cosigner to sign when the draft has one, your company has a default signer, and every mandatory field of the agreement that a draft field fills is filled. Once the rest of the draft is ready, PE also fills the agreement from the project the send would create, without creating it, and reports any field the agreement would leave blank. Each issue has `step` (the builder step: `customer`, `system`, `equipment`, the state's disclosures step, `financials`, `sales`), `field` (the body field), `code`, `message` and `severity`, plus `incentiveId` on an included incentive amount issue. The codes: `DRAFT_FIELD_REQUIRED`, `DRAFT_FIELD_INVALID`, `PAYMENTS_DO_NOT_SUM`, `PAYMENT_ONE_TOO_HIGH`, `PAYMENT_EXCEEDS_NET_AMOUNT_DUE`, `ADDITIONAL_PRODUCT_EXCEEDS_EPC`, `PTO_BEFORE_INSTALL`, `MILESTONE_NAME_INVALID`, `COSIGNER_EMAIL_SAME_AS_CUSTOMER`, `EQUIPMENT_MANUFACTURER_MISMATCH`, `EQUIPMENT_NOT_FOR_SYSTEM_TYPE`, `INSTALL_BEFORE_CONTRACT`, `SYSTEM_SIZE_OUT_OF_RANGE`, `UTILITY_NOT_RECOGNIZED`, `UTILITY_NOT_SERVING_ZIP`, `ZIP_CODE_NOT_IN_STATE`, `STATE_NOT_ACTIVE_FOR_INSTALLER`, `PRICING_NOT_CALCULATED`, `PRICING_STALE`, and the agreement's: `CONTRACT_TEMPLATE_NOT_FOUND`, `COSIGNER_NOT_SUPPORTED`, `AUTO_SIGNER_REQUIRED`, `CONTRACT_DATA_MISSING` (a value from your company's settings; `field` is empty) and `CONTRACT_NOT_SENDABLE`. An issue with `severity: "warning"` (`UTILITY_NOT_SERVING_ZIP`: the utility is not listed for the site ZIP code; `ZIP_CODE_NOT_IN_STATE`: PE's ZIP list puts the site ZIP code in another state; `CONTRACT_CHECKS_UNAVAILABLE`: PE could not run the agreement checks right now, so validate again later, and the send runs them again) does not block the send. A mandatory agreement field that a draft field fills is `DRAFT_FIELD_REQUIRED` on that field, with its label, never the agreement's internal field id. Send the fixes with `PATCH` (objects merge, lists replace, `null` clears) and read `validation` again. Use `?dryRun=true` on `POST /contract-drafts` to check a body without saving it.

    The rep can edit the draft in the portal. `POST /contract-drafts/{draftId}/validate` checks the values the draft holds now, portal edits included, without a write. A `PATCH` builds the draft again from your body and your prefill, so it replaces edits the rep made in the portal. A draft that is being sent or was sent cannot be changed or deleted (`DRAFT_SEND_IN_PROGRESS`, `DRAFT_ALREADY_SENT`).

    ### Send a draft for e-signature

    `POST /contract-drafts/{draftId}/send` (scope `contracts:send`, `X-PE-Actor-Email` required, no body) sends a draft. PE first checks the values the draft holds now, portal edits included: a draft that is not ready returns `DRAFT_NOT_READY` with its issues in `details`. The rep who owns the draft is the sender: the contract goes out in the rep's name, so the rep's role must be administrator or editor (`ASSIGNEE_NOT_PERMITTED` otherwise; an operations user can own a draft but cannot send it). Before anything is created, PE also checks that a customer agreement is published for the state (`CONTRACT_TEMPLATE_NOT_FOUND`), that the agreement has a cosigner signature when the draft has a cosigner (`CONTRACT_NOT_SENDABLE`), that your company has a default signer for the agreement (`AUTO_SIGNER_REQUIRED`), that your company can create projects in the state (`INSTALLER_ON_HOLD`, `STATE_NOT_ACTIVE_FOR_INSTALLER`), and that the agreement filled from the project the send would create has every mandatory field (`DRAFT_NOT_READY` with the missing fields as issues). The draft is unchanged after any of these: fix it with `PATCH` and send again. Then PE:

    1. Creates the project from the draft with your `externalId` (one that another project uses returns `EXTERNAL_ID_IN_USE`), the rep as the sales rep, and the same checks and defaults as a project created in the portal.
    2. Sends the contract the way Send in the portal does: PE fills the agreement from the project, your default signer's signature goes on the installer line, and PE emails the signing link to the homeowner.
    3. Marks the draft `sent` with its `projectId` and `packetId`. The draft leaves the rep's Drafts tab.

    The answer (HTTP 201) has `projectId`, `packetId`, `draftId`, `status`, `signers` (`role`, `name`, `email`, `status`), `installerSignMethod`, `installerSigningUrl`, `testMode` and `warnings`. Sending a sent draft again returns the same answer with HTTP 200 and sends nothing, so a retry after a timeout is safe; `status` and `signers` are the contract's as they are now. When that contract is no longer out for signature (voided, declined or expired), `warnings` has `PACKET_NOT_OPEN` and `installerSigningUrl` is `null` (the link no longer opens the contract): read the project's current contract with `GET /projects/{projectId}/contract-esign`, or send a new one with `POST /projects/{projectId}/contract-esign/send`. A second send while the first one is still running returns `DRAFT_SEND_IN_PROGRESS` (409): read the draft again in a minute.

    If PE created the project but could not send the contract, the answer is an error that names the project: `AUTO_SIGNER_REQUIRED` or `CONTRACT_NOT_SENDABLE` (422) when something has to be fixed first, `CONTRACT_SEND_FAILED` (502) when PE could not send it right now. `details` has the `projectId` and the draft's status is `sent_create_only`. Fix the cause, then send again with `POST /contract-drafts/{draftId}/send` (PE does not create a second project, and does not send twice when a contract is already out) or with `POST /projects/{projectId}/contract-esign/send`. Before a send again on a `sent_create_only` draft, PE checks that the draft's project is the one this key's send created; if it is not, the answer is `DRAFT_STATE_INVALID` (409) and nothing is sent. Because the agreement is filled and checked before the project is created, this is rare: a cause that is not in the draft (your default signer, a setting at PE, a service that was down) is fixed outside the draft, and the send again uses the project as it is. A `sent_create_only` draft cannot be changed; to change the project, use `PATCH /projects/{projectId}` or the Installer Portal, then send again.

    ### When the rep sends the draft from the portal

    The rep can open the draft in the Contract Builder and send it from there instead. Only one of the two sends goes through. While the rep's send is creating the project, `POST /contract-drafts/{draftId}/send` returns `DRAFT_SEND_IN_PROGRESS` (409). Once the rep's project exists, the draft is `sent` with `sentVia` `portal` and the `projectId`, and a send through the API returns that answer with HTTP 200 and creates nothing. If your software sent the draft first, the portal tells the rep that the draft was already sent and creates nothing. If PE refuses the rep's create before the project is written (for example a missing field), the draft goes back to `draft`. If the portal cannot tell whether the project was created (a network error or a timeout), the draft stays `sending` and the rep is told to check the Projects list. If the rep's send stops before the portal confirms it (for example the browser closes), the draft stays `sending`; after 6 minutes a send through the API returns `DRAFT_PORTAL_SEND_UNCONFIRMED` instead of sending, because the project may already exist. Check the portal, then delete the draft if no project was created. On a draft sent from the portal, `packetId` stays `null`, because the rep sends the contract after the project is created: read the contract with `GET /projects/{projectId}/contract-esign`, and `project.contract_status_changed` reports it like any contract of your company. The portal does not copy your `externalId` onto the project; set it with `PATCH /projects/{projectId}`. A sent draft, whoever sent it, leaves the rep's Drafts tab and stays readable through the API.

    ### What the homeowner receives

    The homeowner gets an email from Participate Energy with a link to read and sign the contract online: the customer agreement for the site's state, with the documents PE attaches to it for the project, filled in from the project, and the federal notice of the right to cancel. A cosigner gets their own link. The signers sign in the order the agreement sets. The link stops working when the contract is voided or expires.

    ### The installer signature

    Your company's default signer for the agreement signs the installer line. An administrator sets the default signer once in the Installer Portal (Administration, E-sign Setup). PE applies the stored signature when it sends, so `installerSignMethod` is `auto_applied`, the installer signer's `status` is `signed` at once, and `installerSigningUrl` is `null`: nobody at your company signs each contract. Without a default signer the send returns `AUTO_SIGNER_REQUIRED` before the project is created.

    ### Contract status

    `GET /projects/{projectId}/contract-esign` (scope `projects:read`) returns the project's current contract: its newest contract sent for e-signature that is not cancelled, whether your software or a rep in the portal sent it. A project without one returns `PACKET_NOT_FOUND`. The answer has `packetId`, `status`, `templateName`, `installerSignMethod`, `sentAt`, `completedAt`, `expiresAt`, `voidedReason`, `declineReason`, `signers` and `testMode` (Test keys also get `documents`, see below).

    | `status` | Meaning |
    |---|---|
    | `sent` | Out for signature. |
    | `partially_signed` | Some signers signed. |
    | `completed` | Every signer signed. |
    | `declined` | A signer declined. `declineReason` has the reason they gave. |
    | `voided` | The contract was voided, by your company, by PE or by a newer send. `voidedReason` has the reason when PE has one. |
    | `expired` | The signing window ended before every signer signed. |
    | `cancelled` | The contract was cancelled. |

    Each signer has `role` (`customer`, `cosigner`, `installer`, `pe`), `name`, `email` (`null` for the `pe` signer), `status` (`pending`: not their turn yet; `sent`: their turn, the link is out; `viewed`; `signed`; `declined`), `signedAt` and `viewed`.

    ### Void and send again

    `POST /projects/{projectId}/contract-esign/void` (scope `contracts:send`, `X-PE-Actor-Email` required) with `{"reason": "..."}` voids the current contract. PE records the reason. A contract that is completed or already voided returns `PACKET_NOT_VOIDABLE`.

    A sent contract cannot be edited. To change it, change the project (for example with `PATCH /projects/{projectId}` or `PUT /projects/{projectId}/financials`), then call `POST /projects/{projectId}/contract-esign/send` (scope `contracts:send`, `X-PE-Actor-Email` required). PE voids the contract that is out and sends a new one built from the project as it is now. A signed (completed) contract is never sent over: the send returns `CONTRACT_ALREADY_SIGNED` (409). The sender is the user in `assignedToEmail` (optional body) or else the `X-PE-Actor-Email` user, and their role must be administrator or editor. The answer is the same as a draft send, with `draftId: null`.

    ### The contract webhook

    When the contract of one of your projects changes, PE sends `project.contract_status_changed` (see Webhooks). `data` has `projectId`, `externalId`, `packetId`, `status`, `signers` (`role`, `status`, `signedAt`) and `occurredAt`. PE sends one event for each new state of the contract: the send, a view, each signature and the end (completed, declined, voided, expired, cancelled). Two changes inside one check of about 5 minutes arrive as one event with the newer state. Read `GET /projects/{projectId}/contract-esign` when you need the names and emails.

    Example:

    ```json
    {
      "id": "evt_8c1d2e3f4a5b6c7d8e9f0a1b",
      "type": "project.contract_status_changed",
      "createdAt": "2026-11-12T19:05:00.000Z",
      "environment": "live",
      "data": {
        "projectId": "CA2611-EXAM1",
        "externalId": "crm-10442",
        "packetId": "pkt4Hn8Qa2Zt6WcYb1Lm",
        "status": "completed",
        "signers": [
          {"role": "customer", "status": "signed", "signedAt": "2026-11-12T19:01:44.000Z"},
          {"role": "installer", "status": "signed", "signedAt": "2026-11-12T18:02:12.000Z"}
        ],
        "occurredAt": "2026-11-12T19:01:44.000Z"
      }
    }
    ```

    ### Drafts and contracts in the Test environment

    A Test key validates and prices drafts the same way and returns the same shapes, but its drafts live in PE's test database: they never show in the portal, `portalUrl` is `null`, and they are removed 90 days after the last change. The rep in `assignedToEmail` is still checked against your real users.

    A Test send runs every check a production send runs (the draft, the rep's role, your state, the agreement, your default signer) and answers the same way, but it creates a Test project and a simulated contract, and it emails nobody. PE renders the real contract PDF, the same agreement and fields a production send prints, marked as a test, with your default signer's name but not their signature image. PE keeps it for 30 days. `GET /projects/{projectId}/contract-esign` returns it in `documents` with a download link that works for 15 minutes. If PE could not make the PDF, the contract is still recorded with `documentsRendered: false` and `documentsNotRenderedReason`; send again to retry. Move the contract along with `POST /sandbox/projects/{projectId}/simulate` and the `contract_*` events (see Sandbox). Each change sends `project.contract_status_changed` to your Test webhook URL.

    ### Worked example

    ```http
    POST /v2/installer/contract-drafts
    Authorization: Bearer ik_live_...
    X-PE-Actor-Email: riley@acme-solar.example
    Content-Type: application/json

    {
      "externalId": "crm-10442",
      "customer": {"firstName": "Jordan", "lastName": "Example", "email": "jordan@example.com", "phone": "555-010-0199"},
      "siteAddress": {"street": "100 Example Street", "city": "Sacramento", "stateCode": "CA", "zipCode": "95814"},
      "utility": {"name": "Pacific Gas & Electric"},
      "system": {"systemType": "Solar Only", "annualUsageKwh": 10500, "annualProductionKwh": 12000},
      "equipment": [
        {"category": "module", "avlItemId": "avl_mod_123", "quantity": 25},
        {"category": "inverter", "avlItemId": "avl_inv_456", "quantity": 25},
        {"category": "racking", "avlItemId": "avl_rack_789"}
      ],
      "financials": {"epcAmount": 32000, "dcBonusRecipient": "customer"},
      "stateFields": {"utilityBillsUsed": "Yes", "preSolarTariff": "E-TOU-C", "postSolarTariff": "E-ELEC", "estimatedSavingsMaxBill": 1450}
    }
    ```

    The answer (HTTP 201) has the `draftId`, the stored `pricing` with its `netAmountDue`, and `validation.issues`, for example `PAYMENTS_DO_NOT_SUM` when your prefill has no milestone percentages. Send the payments, then hand the rep the `portalUrl`:

    ```http
    PATCH /v2/installer/contract-drafts/cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
    X-PE-Actor-Email: riley@acme-solar.example

    {"financials": {"payments": [{"amount": 500}, {"name": "Install Complete", "amount": 23180.36}]}}
    ```

    Then send it and read its status:

    ```http
    POST /v2/installer/contract-drafts/cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K/send
    Authorization: Bearer ik_live_...
    X-PE-Actor-Email: riley@acme-solar.example
    ```

    The answer (HTTP 201):

    ```json
    {
      "data": {
        "projectId": "CA2611-EXAM1",
        "packetId": "pkt4Hn8Qa2Zt6WcYb1Lm",
        "draftId": "cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K",
        "status": "sent",
        "installerSignMethod": "auto_applied",
        "installerSigningUrl": null,
        "signers": [
          {"role": "customer", "name": "Jordan Example", "email": "jordan@example.com", "status": "sent"},
          {"role": "installer", "name": "Morgan Owner", "email": "morgan@acme-solar.example", "status": "signed"}
        ],
        "testMode": false,
        "warnings": []
      }
    }
    ```

    Jordan gets the signing email. `GET /v2/installer/projects/CA2611-EXAM1/contract-esign` shows each signer as they view and sign, and `project.contract_status_changed` tells your webhook when to read it.

    ## Sandbox

    The Test environment simulates PE's reviews. These endpoints work only with Test keys. A production key gets `SANDBOX_ONLY`.

    ### Contract upload scenarios

    Send `sandboxScenario` in `POST /contract-uploads` to choose the result. The default is `project_created`. `GET /sandbox/scenarios` lists them. A Test submit applies the scenario at once.

    | `sandboxScenario` | Status | Result |
    |---|---|---|
    | `project_created` | `project_created` | The contract passes review and a sandbox project is created with no open Actions. |
    | `project_created_action_required` | `project_created` | The contract passes review and a sandbox project is created with two open Actions for the installer. |
    | `draft_failed_basic_tests` | `needs_attention` | The contract fails the basic checks. No project is created; the failed checks are in errors. |
    | `draft_invalid_document` | `needs_attention` | The file is not a Participate Energy customer agreement. No project is created. |
    | `draft_duplicate` | `needs_attention` | The contract matches an existing project of the installer. No project is created. |
    | `product_mismatch` | `needs_attention` | The contract is for the other product than the upload productType. No project is created. |
    | `canon_rejected` | `failed` | The contract data fails Participate Energy's project checks. No project is created. |
    | `sibyl_error` | `failed` | The review fails with a processing error. No project is created. |

    ### Simulate PE's work on a project

    `POST /sandbox/projects/{projectId}/simulate` applies one event to a Test project. PE changes the project the same way a real review would: review statuses, Actions, milestone and approval dates. An approval also sends the webhook event at the next check. A new Action (`document_rejected` or `action_raised`) sends `project.action_created` at one of the next two checks. The `contract_*` events change the project's current Test contract instead (send one first with `POST /contract-drafts/{draftId}/send`), and each change sends `project.contract_status_changed`; the answer's `contract` has the contract's `packetId`, `status` and `signers`.

    | `event` | Fields | What changes |
    |---|---|---|
    | `document_approved` | `documentType` | PE approves the slot. Its open Actions close. The slot must have a file. |
    | `document_rejected` | `documentType`, `reason` | The slot moves to Response Needed with a new Action that carries `reason`. The slot must have a file. |
    | `action_raised` | `title`, optional `documentType` | PE raises a new Action, on the slot when you name one. The webhook sends `project.action_created`. |
    | `photos_approved` | none | PE approves the photos. The photo Actions close. |
    | `ic_approved` | none | PE sets the IC approval date. Open Actions close. The webhook sends `project.ic_approved`. |
    | `pc_approved` | none | PE sets the PC approval date. Needs IC approval first. The webhook sends `project.pc_approved`. |
    | `project_cancelled` | none | PE cancels the project. It stays readable and cannot change. |
    | `contract_viewed` | none | The signer whose turn it is opens the contract. |
    | `contract_signed` | none | Every signer who has not signed signs. The contract is `completed`. |
    | `contract_declined` | optional `reason` | The signer whose turn it is declines. The contract is `declined`. |
    | `contract_voided` | optional `reason` | The contract is voided. A completed contract cannot be voided. |
    | `contract_expired` | none | The signing window ends. The contract is `expired`. |

    ## Pagination

    List endpoints return one page and a `nextCursor`. A cursor is opaque: do not build or change one. Send `cursor=<nextCursor>` with the same filters to get the next page. `nextCursor` is `null` on the last page. A cursor works only with the same filters. A changed cursor returns `CURSOR_INVALID`. Set the page size with `limit`.

    | Endpoint | Default `limit` | Maximum `limit` |
    |---|---|---|
    | `GET /projects` | 25 | 100 |
    | `GET /projects/{projectId}/activity` | 50 | 100 |
    | `GET /avl` | 100 | 500 |
    | `GET /equipment-map` | 200 | 500 |

    To sync projects, call `GET /projects?updatedSince=<time>` and keep the latest `updatedAt` you saw.

    ## Rate limits and daily quotas

    | Limit | Value | Applies to |
    |---|---|---|
    | Reads | 120 per minute | Each key: GET calls, eligibility and tax checks |
    | Writes | 60 per minute | Each key: PATCH, PUT, DELETE, submit, confirm, archive, restore, Actions, webhooks, simulate |
    | Pricing | 60 per minute | Each key: `POST /pricing/lease`, `GET /pricing/sungage/products`, `POST /pricing/sungage` |
    | Upload creates | 30 per minute | Each key: `POST /contract-uploads`, document and photo upload creates |
    | Failed authentication | 30 per minute | Each IP address |
    | Contract uploads | 200 per day (production), 50 per day (Test) | Your company. The day is the UTC day. |
    | Document and photo files | 2000 per day (production), 500 per day (Test) | Your company. 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. Responses that pass the per-minute check carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds). `GET /me` shows the limits for your key. PE can change a limit for your company.

    ## Versioning

    The version is in the path: `/v2/installer`. In v2, PE can add endpoints, optional request fields, response fields, enum values 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.

    The Installer API v1 (`/v1`) stays live for 3 to 6 months after v2 opens. Then PE retires it. PE tells you by email before that date. v2 does not accept v1 keys or v1 request shapes. Move one integration at a time and test each one in the Test environment.

    ## Support

    Email raceway.support@participate.energy. Include the request id (`X-Request-Id`), the time, the endpoint and the error code. Never send an API key or a webhook signing secret.

    ## Build with an AI assistant

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

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

    Give the assistant the OpenAPI file and the guide. Ask it to follow the guide: keep the key on the server, send `X-PE-Actor-Email` on writes, send every upload header, poll uploads with backoff, verify webhook signatures, follow cursors and handle every error code. Test all the generated code in the Test environment before you use a production key.

    ## 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/installer/states, or request the state in the Installer Portal.",
        "retryable": false,
        "details": [],
        "docsUrl": "https://api.participate.energy/docs/installer/v2/#error-STATE_NOT_ACTIVE_FOR_INSTALLER"
      },
      "meta": {
        "requestId": "req_9Bv4Nc7Xz2Lk5Hj8Gf3D",
        "environment": "live",
        "timestamp": "2026-11-11T18: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, the eligibility and tax checks and the pricing calls are safe to repeat.
    5. The confirm calls are safe to repeat: a repeat returns the result of the first confirm. A contract upload submit is safe to repeat after a 5xx error.
    6. A create call (`POST /contract-uploads`, document and photo upload creates) makes a new upload each time. If you lost its response, create a new one. An unused upload expires after 15 minutes. A repeated contract upload with the same `externalId` returns `EXTERNAL_ID_IN_USE` until the first one expires. PE does not support an `Idempotency-Key` header: PE ignores it, so a retried create makes a second upload and counts toward the daily limit.
    7. A write with `expectedUpdatedAt` is safe to repeat: when the first try saved, the repeat returns `PROJECT_CHANGED_SINCE_READ`. Read the project to confirm.

    ### Common errors

    Every endpoint can return these codes: [`AUTH_HEADER_MISSING`](#error-AUTH_HEADER_MISSING), [`AUTH_HEADER_MALFORMED`](#error-AUTH_HEADER_MALFORMED), [`KEY_IS_V1`](#error-KEY_IS_V1), [`KEY_IS_DESIGN_API`](#error-KEY_IS_DESIGN_API), [`KEY_INVALID`](#error-KEY_INVALID), [`KEY_REVOKED`](#error-KEY_REVOKED), [`KEY_EXPIRED`](#error-KEY_EXPIRED), [`INSTALLER_API_SUSPENDED`](#error-INSTALLER_API_SUSPENDED), [`ENVIRONMENT_NOT_ENABLED`](#error-ENVIRONMENT_NOT_ENABLED), [`INSTALLER_NOT_ELIGIBLE`](#error-INSTALLER_NOT_ELIGIBLE), [`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 that need the actor header can also return [`ACTOR_REQUIRED`](#error-ACTOR_REQUIRED). 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.

    When: The body is not valid JSON.

    PE's hosting platform reads a body sent with `Content-Type: application/json` before the API does. If that body is not valid JSON (for example a trailing comma), or is a bare JSON value such as `null`, the platform answers HTTP 400 with a plain "Bad Request" page, no JSON error body and no `X-Request-Id`: the API never sees the request. Treat an HTTP 400 without a JSON error body as INVALID_JSON.

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

    When: A field is missing, has the wrong type, or is out of range.

    Each entry in `details` has `field` (a dotted path such as `customer.email`, or `query.limit` for a query parameter), `issue`, and when known `expected` and `received`.

    #### UNKNOWN_FIELD

    HTTP 400. Retry the same request: no.

    > The request has {count} field(s) this endpoint does not accept: {fields}. Allowed fields: {allowed}. Remove the other fields and send the request again.

    When: The body or the query string has a field that the endpoint does not accept. PE rejects unknown fields so that a typo never goes unnoticed. The message lists the allowed fields.

    #### CURSOR_INVALID

    HTTP 400. Retry the same request: no.

    > The cursor is not valid for this list. Send the nextCursor from the previous page of the same request without changes, or leave cursor out to start at the first page.

    When: The `cursor` is not one that PE issued for this list and these filters. A cursor also stops working when PE publishes a new AVL version.

    #### ACTOR_REQUIRED

    HTTP 400. Retry the same request: no.

    > This endpoint needs the X-PE-Actor-Email header. Send the email of the person doing the work (for example your sales rep) as Raceway knows it.

    When: The endpoint needs `X-PE-Actor-Email`, and the request has no such header. Every write and every Sungage call needs it.

    #### ACTOR_INVALID_EMAIL

    HTTP 400. Retry the same request: no.

    > The X-PE-Actor-Email header is not a valid email address. Send one email address, for example rep@installer.example.

    When: `X-PE-Actor-Email` is not one valid email address.

    #### SANDBOX_FIELD_IN_LIVE

    HTTP 400. Retry the same request: no.

    > The field {field} works only with a test key. Remove it from requests made with a live key.

    When: A request with a production key sends a Test-only field, such as `sandboxScenario`.

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

    When: The webhook URL is not an absolute URL, is too long, has a user name or password, or has no public host name.

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

    When: The webhook URL does not use https on port 443.

    #### SANDBOX_SCENARIO_INVALID

    HTTP 400. Retry the same request: no.

    > The sandboxScenario {received} is not one of: {allowed}. Send one of the scenarios from GET /v2/installer/sandbox/scenarios, or leave it out for project_created.

    When: `sandboxScenario` is not one of the Test scenarios.

    ### HTTP 401: authentication

    #### AUTH_HEADER_MISSING

    HTTP 401. Retry the same request: no.

    > The request has no Authorization header. Send "Authorization: Bearer <key>" with your Installer API key. Keys start with ik_test_ or ik_live_.

    When: The request has no Authorization header.

    #### AUTH_HEADER_MALFORMED

    HTTP 401. Retry the same request: no.

    > The Authorization header does not hold an Installer API key. Send "Authorization: Bearer <key>", where the key starts with ik_test_ or ik_live_ followed by 40 letters and digits, with no spaces or line breaks.

    When: The Authorization header is not `Bearer ` followed by a key of the right shape. A key is `ik_test_` or `ik_live_` and 40 letters and digits.

    #### KEY_IS_V1

    HTTP 401. Retry the same request: no.

    > This is an Installer API v1 key (it starts with pk_). v1 keys work only at https://api.participate.energy/v1. Use an Installer API v2 key (ik_test_ or ik_live_) here, or ask Participate Energy for one at raceway.support@participate.energy.

    When: You sent an Installer API v1 key (`pk_...`) to v2. v1 keys keep working at `/v1` until v1 is retired.

    #### KEY_IS_DESIGN_API

    HTTP 401. Retry the same request: no.

    > This is a Design API credential or access token. Design API credentials work only at https://api.participate.energy/v2/design. The Installer API v2 takes an installer key that starts with ik_test_ or ik_live_.

    When: You sent a Design API client id (`dc_...`) or a Design API access token. Design API credentials are for design software vendors. They do not work here.

    #### KEY_INVALID

    HTTP 401. Retry the same request: no.

    > The key is not recognized. Check that the full key was copied without spaces, or ask Participate Energy for a new key at raceway.support@participate.energy.

    When: The key has the right shape, but PE has no record of it. The key was mistyped, cut short, or never issued.

    #### KEY_REVOKED

    HTTP 401. Retry the same request: no.

    > The key {keyPrefix} was revoked. Use another active key, or ask Participate Energy for a new one at raceway.support@participate.energy.

    When: PE revoked the key. A revocation takes effect within 60 seconds.

    #### KEY_EXPIRED

    HTTP 401. Retry the same request: no.

    > The key {keyPrefix} expired at {expiredAt}. Keys last 12 months; ask Participate Energy for a new key at raceway.support@participate.energy.

    When: The key is more than 12 months old. Keys expire 12 months after PE creates them.

    ### HTTP 403: access

    #### INSTALLER_API_SUSPENDED

    HTTP 403. Retry the same request: no.

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

    When: PE suspended Installer API access for your company. Every key of your company gets this code until PE lifts the suspension.

    #### ENVIRONMENT_NOT_ENABLED

    HTTP 403. Retry the same request: no.

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

    When: PE turned off the environment of the key (Test or Production) for your company.

    #### INSTALLER_NOT_ELIGIBLE

    HTTP 403. Retry the same request: no.

    > Your organization is not set up as a Participate Energy install partner, so this key cannot be used. Contact Participate Energy at raceway.support@participate.energy.

    When: The organization that owns the key is no longer set up as a PE install partner. A contract upload also gets this code when PE's counterparty check refuses the organization.

    #### SANDBOX_ONLY

    HTTP 403. Retry the same request: no.

    > This endpoint works only with Test keys (ik_test_). Send the request with your Test key.

    When: You called a `/sandbox` endpoint with a production key (`ik_live_`).

    #### SCOPE_NOT_GRANTED

    HTTP 403. Retry the same request: no.

    > This endpoint needs the scope {scope}, and your key does not carry it. The key carries: {granted}. Ask Participate Energy for a key with the scope you need.

    When: The endpoint needs a scope that the key does not carry. `details` names the scope that is needed and the scopes of the key.

    Ask PE for a key with the scope. For a production key, make at least one successful Test call with that scope first.

    #### ACTOR_NOT_ON_ROSTER

    HTTP 403. Retry the same request: no.

    > The X-PE-Actor-Email address is not an active Raceway user of your company, and its domain is not one of your allowed domains. Send the email of the person doing the work as Raceway knows it, or add the user in Raceway first.

    When: The `X-PE-Actor-Email` address is not an active user of your company (or of an organization below it), and its domain is not one of your company's allowed domains.

    #### 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/installer/states, or request the state in the Installer Portal.

    When: A contract upload names a state where your company is not active yet. `POST /eligibility` reports the same code in its `installer_state` check, and pricing reports it as a warning.

    #### PRODUCT_NOT_ENABLED

    HTTP 403. Retry the same request: no.

    > The product {productType} is not enabled for this installer. Contact Participate Energy to turn it on.

    When: A contract upload names a `productType` that PE has not enabled for your company. `POST /eligibility` reports the same code in its `product` check.

    #### 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. Contact Participate Energy to enroll.

    When: A production key calls a Sungage endpoint, and your company is not in the PE and Sungage program, or PE has no Sungage account on file for it.

    #### 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 in the X-PE-Actor-Email header, or register the user with Sungage.

    When: Sungage does not know the `X-PE-Actor-Email` address as a user of your Sungage 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. Contact Participate Energy at raceway.support@participate.energy.

    When: PE put your company's account on hold, so it cannot create new projects.

    #### MONITORING_ACCESS_NOT_ALLOWED

    HTTP 403. Retry the same request: no.

    > Your company cannot change monitoring sites here. {reason} Ask Participate Energy for help.

    When: Your company cannot change the monitoring sites of this project.

    ### HTTP 404: not found

    #### ROUTE_NOT_FOUND

    HTTP 404. Retry the same request: no.

    > No Installer API route matches {received}. Check the method and path against the API reference at https://api.participate.energy/docs/installer/v2/.

    When: No endpoint matches the method and path. Check the path below `/v2/installer`.

    #### RESOURCE_NOT_FOUND

    HTTP 404. Retry the same request: no.

    > No {resource} with this id is available to your key in the {environment} environment. Check the id, and use a key for the environment where the {resource} was created.

    When: The id does not exist, belongs to another installer, or belongs to the other environment. PE gives the same answer in all three cases. A Test key sees only Test projects and uploads. A production key sees only production ones. Ids are case-sensitive. When a project ID or external ID you sent matches one of your projects in another letter case, `details[0].didYouMean` names the exact id.

    #### SAFE_HARBOR_OPPORTUNITY_NOT_FOUND

    HTTP 404. Retry the same request: no.

    > No Safe Harbor opportunity {opportunityId} belongs to this installer. Use an opportunityId from GET /v2/installer/safe-harbor/opportunities.

    When: The Safe Harbor opportunity id is not one of your company's opportunities.

    #### DRAFT_NOT_FOUND

    HTTP 404. Retry the same request: no.

    > No contract draft {draftId} exists for this installer in this environment. List your drafts with GET /v2/installer/contract-drafts.

    When: The draftId does not exist, belongs to another installer, or was created with a key of the other environment. A deleted draft is not found either.

    #### PACKET_NOT_FOUND

    HTTP 404. Retry the same request: no.

    > Project {projectId} has no contract sent for e-signature. Send one with POST /v2/installer/contract-drafts/<draftId>/send or POST /v2/installer/projects/{projectId}/contract-esign/send.

    When: You read, void or simulate the contract of a project that has no contract sent for e-signature, from the API or from the portal.

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

    When: The path exists, but not with this method. The `Allow` header lists the methods the path accepts.

    ### HTTP 409: conflict

    #### EXTERNAL_ID_AMBIGUOUS

    HTTP 409. Retry the same request: no.

    > More than one of your projects uses the externalId {externalId}. Read the project by its projectId instead; the projectIds are in details.

    When: `GET /projects/by-external-id/{externalId}` finds more than one of your projects with this external id. This can happen on older projects. `details` lists the PE Project IDs.

    #### EXTERNAL_ID_IN_USE

    HTTP 409. Retry the same request: no.

    > The externalId {externalId} is already used by this installer. {reason} To create another project, send a different externalId.

    When: A contract upload names an `externalId` that a project of your company uses, or that another contract upload is still processing with, in this environment. A contract draft (create, dry run, or a `PATCH` that changes `externalId`) names one that a project of your company or another open contract draft (not sent yet) uses, in this environment. The message and `details` name the holder (`heldBy` is `project`, `upload` or `draft`, with `draftId`). `EXTERNAL_ID_IN_USE` (contract uploads) and `EXTERNAL_ID_TAKEN` (PATCH) mean the same thing; both codes stay so that existing clients keep working.

    #### UPLOAD_ALREADY_SUBMITTED

    HTTP 409. Retry the same request: no.

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

    When: You submit a contract upload a second time after a successful submit.

    #### PROJECT_CANCELLED

    HTTP 409. Retry the same request: no.

    > Project {projectId} was cancelled, so it cannot be changed. You can still read it. If this is a mistake, contact Participate Energy at raceway.support@participate.energy.

    When: You try to change a project that is cancelled. You can still read it.

    #### PROJECT_LOCKED

    HTTP 409. Retry the same request: no.

    > Project {projectId} cannot be edited at the {milestone} milestone. {reason} If a value must change, contact Participate Energy at raceway.support@participate.energy.

    When: You edit project fields outside the edit window. See Editing rules. `details` gives the milestone and the reason.

    #### CHANGE_ORDER_REQUIRED

    HTTP 409. Retry the same request: no.

    > Project {projectId} passed IC approval, so its {area} can no longer be changed through the API. A change now needs a signed change order: upload it as the project's change order document, or contact Participate Energy at raceway.support@participate.energy.

    When: You change the financials or the equipment of a project that passed IC approval.

    #### CHANGE_ORDER_BLOCKED

    HTTP 409. Retry the same request: no.

    > This change to project {projectId} needs Participate Energy review and cannot be made through the API. Contact Participate Energy at raceway.support@participate.energy.

    When: PE's change order rules refuse the change through the API. The change needs a PE review.

    #### PROJECT_CHANGED_SINCE_READ

    HTTP 409. Retry the same request: no.

    > Project {projectId} changed after you read it. Your expectedUpdatedAt is {expected} but the project's updatedAt is {actual}. Read the project again, then resend the change.

    When: You sent `expectedUpdatedAt`, and the project changed after that time.

    #### EXTERNAL_ID_TAKEN

    HTTP 409. Retry the same request: no.

    > This externalId is already used by project {otherProjectId} of your company. Each project needs its own externalId. Send a different one.

    When: A PATCH sets an `externalId` that another project of your company already uses. It is the PATCH form of `EXTERNAL_ID_IN_USE`.

    #### FINANCIALS_SET_BY_PE

    HTTP 409. Retry the same request: no.

    > Financials on Distributed Microgrid projects are set by PE. Contact PE to change them.

    When: You change the financials of a Distributed Microgrid project. PE sets Distributed Microgrid pricing, so these financials are read-only, as in the Installer Portal.

    #### FINANCIALS_EQUIPMENT_UNRESOLVED

    HTTP 409. Retry the same request: no.

    > Project {projectId} has equipment that is not matched to the approved vendor list yet, so its lease factor is not final. Fix the equipment first with PUT /projects/{projectId}/equipment, then update the financials.

    When: You change the financials of a project whose equipment is not all matched to the AVL. The lease factor depends on the equipment.

    #### EQUIPMENT_DOCUMENTS_SIGNED

    HTTP 409. Retry the same request: no.

    > Project {projectId} has {count} signed document(s) that list its current equipment, such as a Bill of Sale. Changing the equipment voids them, which needs a confirmation in the Installer Portal. Make this equipment change in the portal, or contact Participate Energy at raceway.support@participate.energy.

    When: The equipment change would void signed documents that list the current equipment, such as a Bill of Sale. That change needs a confirmation step that only the Installer Portal has.

    #### SAFE_HARBOR_NOT_FOR_DM

    HTTP 409. Retry the same request: no.

    > Safe Harbor does not apply to Distributed Microgrid projects. Contact PE if this project needs a Safe Harbor opportunity.

    When: You link or clear a Safe Harbor opportunity on a Distributed Microgrid project. The Installer Portal does not offer Safe Harbor on these projects either.

    #### SAFE_HARBOR_OPPORTUNITY_CLOSED

    HTTP 409. Retry the same request: no.

    > Safe Harbor opportunity {opportunityId} is {status} and can no longer be linked. Pick an opportunity that is still open.

    When: The Safe Harbor opportunity is no longer open.

    #### SAFE_HARBOR_NO_UNITS

    HTTP 409. Retry the same request: no.

    > Safe Harbor opportunity {opportunityId} has no units left. Pick another opportunity, or contact Participate Energy at raceway.support@participate.energy.

    When: The Safe Harbor opportunity has no units left.

    #### SAFE_HARBOR_CONSUMED

    HTTP 409. Retry the same request: no.

    > Project {projectId} already used Safe Harbor units, so its opportunity cannot be unlinked through the API. Contact Participate Energy at raceway.support@participate.energy.

    When: You try to unlink or change the Safe Harbor opportunity of a project that already used Safe Harbor units (units are used at IC approval).

    #### DOCUMENT_UPLOAD_CLOSED

    HTTP 409. Retry the same request: no.

    > Uploads of {documentType} are closed on project {projectId}: {reason} Ask Participate Energy if a file still needs to change.

    When: Uploads to this slot are locked. An IC-stage slot locks at IC approval. A PC-stage slot locks at PC approval. Every slot locks when the project is Closed or in cancellation.

    #### DOCUMENT_LOCKED

    HTTP 409. Retry the same request: no.

    > This document cannot change right now. {reason} Ask Participate Energy if it must change.

    When: The document cannot change right now, for example because PE is processing it. The message gives the reason.

    #### FILE_NOT_RECEIVED

    HTTP 409. Retry the same request: yes.

    > No file has arrived for upload {fileUploadId} yet. PUT the file to uploadUrl with the uploadHeaders, then confirm again.

    When: You confirm an upload before the file arrived at the upload URL.

    #### FILE_UPLOAD_IN_PROGRESS

    HTTP 409. Retry the same request: yes.

    > Upload {fileUploadId} is being confirmed by another request. Wait a few seconds, then confirm again to read the result.

    When: Another request is confirming the same upload at this moment.

    #### DOCUMENT_ARCHIVE_BLOCKED

    HTTP 409. Retry the same request: no.

    > Version {version} of {documentType} cannot be archived or restored. {reason} GET /v2/installer/projects/{projectId}/documents shows each version and its state.

    When: The version cannot be archived or restored. For example, the slot is locked by an approval, or PE's archive rules do not allow it for this file. The message gives the reason.

    #### MONITORING_SITE_DUPLICATE

    HTTP 409. Retry the same request: no.

    > A monitoring site is already used on another project: {reason} Check the site ID with the monitoring provider.

    When: A site ID is already used on another project.

    #### MONITORING_ACCESS_CHANGED

    HTTP 409. Retry the same request: no.

    > The monitoring sites changed since you read them. GET the monitoring access again, apply your change, and send it with the new baseSitesHash.

    When: You sent `baseSitesHash`, and the sites changed after you read them.

    #### MONITORING_ACCESS_LOCKED

    HTTP 409. Retry the same request: no.

    > The monitoring sites cannot change right now. {reason} Ask Participate Energy if a site must change.

    When: The monitoring sites cannot change, for example after IC approval.

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

    When: The simulate event does not fit the Test project's state. For example, `pc_approved` before `ic_approved`, or an approval of a slot that has no file.

    #### DRAFT_ALREADY_SENT

    HTTP 409. Retry the same request: no.

    > Contract draft {draftId} was already sent, so it cannot be changed or deleted. Read the project's contract status, or void and re-send the contract.

    When: A PATCH or DELETE on a draft that was sent. Its project exists; change the contract with a void and a new send.

    #### DRAFT_SEND_IN_PROGRESS

    HTTP 409. Retry the same request: yes.

    > Contract draft {draftId} is being sent right now, so it cannot be changed. Read the draft again in a minute.

    When: A PATCH or DELETE while the draft is being sent. Read the draft again in a minute.

    #### PACKET_NOT_VOIDABLE

    HTTP 409. Retry the same request: no.

    > The contract for project {projectId} is {status}, so it cannot be voided. Read it with GET /v2/installer/projects/{projectId}/contract-esign.

    When: You void a contract that is already completed or voided. `details` and the message give its status.

    #### CONTRACT_ALREADY_SIGNED

    HTTP 409. Retry the same request: no.

    > The contract for project {projectId} is signed (completed), so it is not sent again. Read it with GET /v2/installer/projects/{projectId}/contract-esign. A change to a signed contract needs a change order through Participate Energy.

    When: You send a project's contract again (`POST /projects/{projectId}/contract-esign/send`) when its current contract is signed (completed). A signed contract is changed only through a change order.

    ### HTTP 410: gone

    #### 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/installer/contract-uploads; you can use the same externalId.

    When: You submit a contract upload after its 15-minute upload URL expired with no file.

    #### FILE_UPLOAD_EXPIRED

    HTTP 410. Retry the same request: no.

    > The upload URL for {fileUploadId} expired before the file arrived. Create a new upload and send the file within 15 minutes.

    When: You confirm an upload after its 15-minute upload URL expired with no file.

    #### CONTRACT_ESIGN_MOVED

    HTTP 410. Retry the same request: no.

    > POST /v2/installer/contract-esign was replaced in 2.2. Send a contract draft with POST /v2/installer/contract-drafts/<draftId>/send, or send the contract of an existing project again with POST /v2/installer/projects/<projectId>/contract-esign/send.

    When: You called `POST /contract-esign`, the placeholder of version 2.0. Send a contract draft with `POST /contract-drafts/{draftId}/send` 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.

    When: The JSON body is larger than 1 MiB.

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

    When: The contract PDF is larger than 25 MB. PE closes the upload (outcome `file_rejected`).

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

    When: A request with a body has a `Content-Type` other than `application/json`.

    ### HTTP 422: the request breaks a rule

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

    When: PE could not find the street address on the map. This happens on checks and quotes that need the location: the Energy Community check, `energyCommunity: "auto"` in pricing, and the sales tax lookup. `POST /checks/sales-tax` and `POST /checks/energy-community` find the address with Google Maps and need a street number and a street name. Outside Colorado, `POST /checks/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_OUTSIDE_US

    HTTP 422. Retry the same request: no.

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

    When: The address is outside the United States.

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

    When: The site address street is a PO Box or a private mailbox (PO Box, P.O. Box, Post Office Box, POB, P.O.B. or PMB, in any case). Pricing, eligibility and the Energy Community and sales tax checks need the street address where the system is installed. A mailing address can be a PO Box.

    #### STATE_NOT_SUPPORTED

    HTTP 422. Retry the same request: no.

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

    When: The state is not one where PE operates. Pricing and contract uploads refuse it.

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

    When: The address is in a different state than the `stateCode` you sent.

    Lease pricing and contract drafts also refuse a ZIP code that is in another state when Google places the street in your `stateCode` with a different ZIP code: the detail names `address.zipCode` (`siteAddress.zipCode` on a draft) and carries `zipState` and `suggestedZipCode`.

    #### 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/installer/utilities, sending the zipCode of the site address.

    When: `POST /eligibility` reports this code in its `utility` check when the utility does not serve the state. It is a check result inside a 200 response.

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

    When: `POST /eligibility` reports this code in its `ownership` check when you send `ownership: "renter"`. It is a check result inside a 200 response.

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

    When: `POST /eligibility` reports this code in its `existing_solar` check when you send `existingSolarOnProperty: "add_to_existing"`. It is a check result inside a 200 response.

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

    When: An equipment item does not match any item on the AVL or your Equipment Map. On `PUT /projects/{projectId}/equipment`, each entry in `details` carries up to 3 `suggestions` from the AVL.

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

    When: An equipment name matches more than one AVL item. `details` carries the `candidates`. Send the `avlItemId` of the right one.

    #### EQUIPMENT_CATEGORY_MISMATCH

    HTTP 422. Retry the same request: no.

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

    When: In `POST /checks/domestic-content`, a SKU is on the AVL under another category than the one you sent. Send it with the category the message names.

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

    When: A quantity is more than PE accepts on one line: more than 500 modules in `PUT /projects/{projectId}/equipment` or `POST /checks/domestic-content`. A quantity this large is usually the system size in watts.

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

    When: The address is in a taxable jurisdiction, but PE has no lease sales tax rate for it. PE does not guess a rate.

    #### EPC_OUT_OF_RANGE

    HTTP 422. Retry the same request: no.

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

    When: `epcAmount` is outside 1,000 to 500,000 USD on a lease or Sungage price or in `PUT /projects/{projectId}/financials`, or `targetNetAmountDue` is outside that range on the `netAmountDue` basis (it stands in for the EPC). `{field}` names the field, `{amountName}` what it holds (the total EPC, or the Net Amount Due for `targetNetAmountDue`), and `{hint}` names the likely unit mistake: below the range it is often a price per watt or thousands of dollars, above it often cents.

    #### NET_AMOUNT_DUE_OUT_OF_RANGE

    HTTP 422. Retry the same request: no.

    > The targetNetAmountDue {received} cannot be priced: the EPC that gives it must be from {min} to {max} USD. Check the amount and the other inputs.

    When: You priced on the `netAmountDue` basis, and no EPC from 1,000 to 500,000 USD gives the `targetNetAmountDue` with the other inputs. For example, the ineligible roofing cost passes through and sets a minimum. A target outside 1,000 to 500,000 USD is `EPC_OUT_OF_RANGE`.

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

    When: You sent `systemSizeKw` with a lease or Sungage price, and the EPC is less than $1 or more than $10 per watt DC of that size on a `solar_only` system, or less than $1 per watt on `solar_battery` (the EPC also pays for the battery; no upper limit). `battery_only` is not checked. On the `netAmountDue` basis PE checks the EPC it solved. The message shows the computed price per watt.

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

    When: `contractDate` is more than one year before today or more than 90 days after today. The contract date sets the lease factor and the incentive rules, so PE prices only dates in this window.

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

    When: A Hawaii `contractDate` (or `sales.contractDate` on a contract draft) is before 2026-07-03. 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. The API does not accept backdated Hawaii contracts. If the contract was signed before 2026-07-03, contact Participate Energy.

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

    When: An `installer_managed` included incentive amount is the EPC or more, or the incentive would make the Net Amount Due negative.

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

    When: You sent a roofing cost above 0 with `systemType: "battery_only"`.

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

    When: In `POST /checks/sales-tax`, `netAmountDue` is outside 1,000 to 500,000 USD (`0` counts as left out and is not refused). A value this far off is usually in cents or in thousands of dollars.

    #### SYSTEM_SIZE_LOOKS_LIKE_WATTS

    HTTP 422. Retry the same request: no.

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

    When: `systemSizeKw` is above 250 and reads as watts (for example 7200 for a 7.2 kW system), on pricing or in `PUT /projects/{projectId}/equipment`. PE never converts it: send the size in kW DC.

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

    When: `systemSizeKw` is less than 0.5 or more than 250 kW DC and does not read as watts, on pricing or in `PUT /projects/{projectId}/equipment`.

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

    When: A roofing cost is negative or not a number.

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

    When: `safeHarbor.units` is not a whole number from 1 to the units available on the opportunity.

    #### INCENTIVE_NOT_AVAILABLE

    HTTP 422. Retry the same request: no.

    > The incentive {received} is not available: {reason}.

    When: Pricing: the included incentive does not apply to this installer, state or date (`{reason}` reads: it is not an included incentive for this installer or state. Send type "none", or an incentive that applies). Sungage pricing never takes an included incentive. Contract drafts: an id in `financials.includedIncentives` or `financials.incentives` is not offered for the draft's state, system type and utility, or is sent twice; `{reason}` says which list and how to fix it.

    #### 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/installer/pricing/sungage/products.

    When: The Sungage product, term and rate combination is not on the card for this state, or the term is too long for the system type (25 years at most, 20 years at most for `battery_only`).

    #### PRODUCT_NOT_AVAILABLE_IN_STATE

    HTTP 422. Retry the same request: no.

    > The product {productType} is not available in {stateCode}. Send a stateCode where Participate Energy offers the product, or contact raceway.support@participate.energy.

    When: A contract upload names a state where PE does not offer the product.

    #### PRODUCT_NOT_SUPPORTED_BY_API

    HTTP 422. Retry the same request: no.

    > Contract uploads through the API support Synthetic Cash only. Upload Distributed Microgrid contracts in the Installer Portal.

    When: A contract upload asks for Distributed Microgrid, or leaves `productType` out when your company has only Distributed Microgrid enabled. Contract uploads through the API create Synthetic Cash projects only. `GET /me` lists them in `apiContractUploadProducts`.

    `details` has one entry: `field` `productType`, `expected` the products the API can create, and `received` the product you sent (or `omitted`).

    #### UPLOAD_FILE_MISSING

    HTTP 422. Retry the same request: no.

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

    When: You submit a contract upload before the PDF arrived at the upload URL.

    #### UPLOAD_FILE_EMPTY

    HTTP 422. Retry the same request: no.

    > The file for upload {uploadId} is empty (0 bytes). Create a new upload and PUT the signed customer agreement as a PDF; you can use the same externalId.

    When: The file you PUT to the contract upload URL is empty (0 bytes). PE closes the upload; create a new one.

    #### UPLOAD_NOT_PDF

    HTTP 422. Retry the same request: no.

    > The file for upload {uploadId} is not a PDF. Create a new upload and PUT the signed customer agreement as a PDF; you can use the same externalId.

    When: The file does not start with the PDF signature (`%PDF-`). PE closes the upload (outcome `file_rejected`).

    #### FIELD_NOT_EDITABLE

    HTTP 422. Retry the same request: no.

    > "{field}" cannot be set through the API. {hint} Remove the field and send the request again.

    When: A PATCH sends a field that the API shows but never writes. `ptoDate`: the PTO date comes from the PTO letter; upload the letter as the `permissionToOperate` document. `productType`, `contractType` and `site`: they come from the signed contract. `systemType`: a change needs a change order. `status`: PE sets it. `{hint}` gives the reason.

    #### UTILITY_NOT_RECOGNIZED

    HTTP 422. Retry the same request: no.

    > The utility name is not in the Participate Energy utility list. Use a name from GET /utilities, sending the zipCode of the project site, and send the change again.

    When: A PATCH sets a utility name that is not in PE's utility list for the project's state.

    #### PROJECT_UPDATE_REJECTED

    HTTP 422. Retry the same request: no.

    > Participate Energy could not save the change because {count} value(s) failed validation. See details, fix the values and send the change again.

    When: PE's project checks refused one or more values of the change. `details` lists them.

    #### FINANCIALS_INVALID

    HTTP 422. Retry the same request: no.

    > The financials for project {projectId} cannot be computed from these inputs. See details, fix the inputs and send them again.

    When: PE cannot compute the pricing chain from the financial inputs. For example, no EPC from 1,000 to 500,000 USD gives the `targetNetAmountDue` with the project's other inputs, or the inputs give a payout PE cannot make (often an amount in cents): then `details` show the computed `pePayout`, `icPayment` and `pcPayment`.

    #### LENDER_NOT_APPROVED

    HTTP 422. Retry the same request: no.

    > The lender is not on the Participate Energy approved lender list for this project's state. details[0].approved lists the approved lenders; send one of those names, or null for no lender. To have a lender approved, contact Participate Energy at raceway.support@participate.energy.

    When: In `PUT /projects/{projectId}/financials`, `lender` is not on PE's approved lender list for the project's state (the list the Lender picker in the Installer Portal shows). PE matches the name in any case and stores the list's spelling. `details[0].approved` lists the approved names. Send `null` to clear the lender. A resend of the lender the project already has is not checked again.

    #### EQUIPMENT_WRONG_CATEGORY

    HTTP 422. Retry the same request: no.

    > Equipment items that point to an approved vendor list item of another category: {count}. See details, then send each item under its own category.

    When: An equipment item points to an AVL item of another category.

    #### EQUIPMENT_INVALID

    HTTP 422. Retry the same request: no.

    > The equipment change was not accepted ({count} problem(s)). See details, fix the items and send the change again.

    When: The equipment change breaks a rule, for example a battery on a solar-only system or a system size outside the allowed range. `details` lists each problem.

    #### SYSTEM_SIZE_MISMATCH

    HTTP 422. Retry the same request: no.

    > The systemSizeKw {received} does not fit the modules: {basis}. Send the DC size in kW that matches the modules, or fix the module quantity.

    When: In `PUT /projects/{projectId}/equipment`, the `systemSizeKw` you sent is more than 25% away from the module count times the module wattage (the request's module item, else the project's). The same check runs on `system.systemSizeKw` of a contract draft. When the module wattage is not known (an approved vendor list item with no wattage), the size must still be possible for the module count, 250 W to 1,000 W per module. The message names the numbers it compared.

    #### SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER

    HTTP 422. Retry the same request: no.

    > Adding a battery changes the system to Solar + Storage, which needs a change order. Contact PE at raceway.support@participate.energy.

    When: In `PUT /projects/{projectId}/equipment`, you sent a `battery` or `batteryExpansion` item on a Solar Only project that has no battery. A battery changes the system type, which needs a change order.

    #### SAFE_HARBOR_WRONG_INSTALLER

    HTTP 422. Retry the same request: no.

    > Safe Harbor opportunity {opportunityId} belongs to another company in your organization. Pick an opportunity that belongs to the installer of project {projectId}.

    When: The Safe Harbor opportunity belongs to another company in your organization tree.

    #### SAFE_HARBOR_NOT_APPLICABLE

    HTTP 422. Retry the same request: no.

    > Safe Harbor opportunity {opportunityId} cannot be linked to project {projectId}: the project does not meet the opportunity's rules (for example, its equipment is not on the opportunity's custom AVL). Check the equipment, or contact Participate Energy at raceway.support@participate.energy.

    When: The project does not meet the opportunity's rules, for example its equipment is not on the opportunity's custom AVL.

    #### DOCUMENT_TYPE_NOT_UPLOADABLE

    HTTP 422. Retry the same request: no.

    > The document type {documentType} is not one you can upload on project {projectId}. GET /v2/installer/projects/{projectId}/documents lists the document types you can upload.

    When: The document type is not one that an installer can upload on this project, or installers cannot archive files of this type. When the value is close to an allowed one (another case, `_` or spaces, or the display label), `details[0].didYouMean` names it.

    #### PHOTOS_USE_PHOTO_UPLOAD

    HTTP 422. Retry the same request: no.

    > Photos are not uploaded as a document. Use POST /v2/installer/projects/{projectId}/photos/{category}/uploads with the photo category instead.

    When: You sent `photos` as a document type. Photos have their own upload endpoint with a category.

    #### CONTENT_TYPE_NOT_ALLOWED

    HTTP 422. Retry the same request: no.

    > This content type is not accepted for {what}. Send one of: {allowed}.

    When: The `contentType` is not accepted for this kind of file. Documents accept PDF, JPEG, PNG, HEIC and HEIF. Photos also accept WebP and GIF.

    #### FILE_TOO_LARGE

    HTTP 422. Retry the same request: no.

    > The file uploaded for {fileUploadId} is {received} bytes, more than the {max} bytes allowed. Create a new upload with a smaller file.

    When: The uploaded file is larger than the limit (50 MB for a document, 100 MB for a photo). PE rejects the upload. Every later confirm returns the same error.

    #### FILE_EMPTY

    HTTP 422. Retry the same request: no.

    > The file uploaded for {fileUploadId} is empty (0 bytes). Create a new upload and PUT the whole file.

    When: The document or photo file you PUT is empty (0 bytes). PE rejects the upload. Every later confirm returns the same error.

    #### FILE_CONTENT_MISMATCH

    HTTP 422. Retry the same request: no.

    > The file uploaded for {fileUploadId} is not a valid {expected} file: its first bytes look like {detected}, not the content type you declared. Create a new upload with the correct contentType and file.

    When: The first bytes of the file do not match the `contentType` you declared. PE checks the file signature: `%PDF` for PDF, the JPEG and PNG signatures, `RIFF` and `WEBP` for WebP, `GIF8` for GIF, and an `ftyp` box with a HEIF brand (`heic`, `heix`, `hevc`, `heim`, `heis`, `hevm`, `hevs`, `mif1`, `msf1`) for HEIC and HEIF. The message names the type the first bytes look like (for example `image/png`), or "another file type". PE rejects the upload. Every later confirm returns the same error.

    #### PHOTO_CATEGORY_UNKNOWN

    HTTP 422. Retry the same request: no.

    > The photo category {category} does not exist. GET /v2/installer/projects/{projectId}/photos lists the categories for this project.

    When: The photo category in the path is not a PE photo category. When the value is close to an allowed one (another case, `_` or spaces, or the display label), `details[0].didYouMean` names it.

    #### MONITORING_ACCESS_INVALID

    HTTP 422. Retry the same request: no.

    > The monitoring sites are not valid: {reason} Fix the sites listed in details and send the request again.

    When: A monitoring site is not valid, for example a site ID in the wrong format for its provider.

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

    When: The webhook host resolves to a private, local or reserved IP address.

    #### WEBHOOK_NOT_CONFIGURED

    HTTP 422. Retry the same request: no.

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

    When: You rotate the secret or send a test event, and no webhook URL is set for the environment of the key.

    #### SANDBOX_DOCUMENT_TYPE_UNKNOWN

    HTTP 422. Retry the same request: no.

    > The documentType {documentType} is not a document slot of this project. Use a documentType from GET /v2/installer/projects/{projectId}/documents.

    When: A simulate event names a `documentType` that is not a document slot of the Test project. When the value is close to an allowed one (another case, `_` or spaces, or the display label), `details[0].didYouMean` names it.

    #### DRAFT_NOT_READY

    HTTP 422. Retry the same request: no.

    > Contract draft {draftId} is not ready to send: {count} issue(s). Fix each issue in details with PATCH /v2/installer/contract-drafts/{draftId}, then send again.

    When: A send was asked for a draft whose `validation.readyToSend` is false. `details` lists the issues.

    #### DRAFT_PORTAL_SEND_UNCONFIRMED

    HTTP 409. Retry the same request: no.

    > The rep started sending contract draft {draftId} from the Installer Portal and it did not finish. Check the rep's Projects list for this customer before you send again. If no project was created, delete this draft and create a new one.

    When: A send through the API on a draft the rep started sending from the Installer Portal more than 6 minutes ago, where the portal never confirmed the project. The project may exist. The API does not send this draft. A `DELETE` of the draft is allowed in this state.

    #### DRAFT_STATE_INVALID

    HTTP 409. Retry the same request: no.

    > Contract draft {draftId} was changed outside the API and no longer points to a project your integration created from it, so it was not sent. Check the rep's Projects list for this customer before you create a new draft.

    When: A send through the API on a draft whose stored link to its project was changed outside the API: the project is not one that a draft send through the Installer API created for your company, it does not carry the draft's `externalId`, or a `sent_create_only` draft lost its project. Nothing is created or sent.

    #### ASSIGNEE_NOT_FOUND

    HTTP 422. Retry the same request: no.

    > The assignedToEmail is not an active user of this installer. Send the email of an active Installer Portal user of your organization, or leave it out to assign the draft to the X-PE-Actor-Email user.

    When: `assignedToEmail` (or, without it, the X-PE-Actor-Email user) is not an active Installer Portal user of your company, or neither was sent.

    #### ASSIGNEE_NOT_PERMITTED

    HTTP 422. Retry the same request: no.

    > The assigned user has the role {role}, which cannot {action}. Assign a user with one of these roles: {allowed}.

    When: The user's role cannot create projects in the Installer Portal (administrator, editor and operations can).

    #### PREFILL_LOCKED_FIELD

    HTTP 422. Retry the same request: no.

    > Your organization's prefill locks {field} to {lockedValue} for this state. Leave {field} out, or send the locked value. GET /v2/installer/contract-drafts/defaults?stateCode={stateCode} lists the locked fields.

    When: Your prefill locks the payment instructions or the DC bonus recipient for the state, and the body sends a different value.

    #### EQUIPMENT_NOT_ALLOWED_BY_PREFILL

    HTTP 422. Retry the same request: no.

    > Your organization's prefill does not allow {item} ({category}) in {stateCode}. Choose another item; GET /v2/installer/contract-drafts/defaults?stateCode={stateCode} lists the excluded items.

    When: An equipment line resolves to an AVL item that your prefill excludes for the state.

    #### DRAFT_FIELD_REQUIRED

    HTTP 422. Retry the same request: no.

    > A field the contract needs is missing. The issue names the field; send it with PATCH /v2/installer/contract-drafts/{draftId}.

    When: A validation issue: a field the Contract Builder requires before it sends is empty. The issue's `field` and `step` name it. For the amount of an included incentive the message names the incentive, for example `Amount for the included incentive "NY-Sun" (ny-nysun) is required.`, and the issue carries its `incentiveId`.

    #### DRAFT_FIELD_INVALID

    HTTP 422. Retry the same request: no.

    > A field value is not in the form the contract needs (an email, a phone with 10 or 11 digits, or a ZIP code). The issue names the field.

    When: A validation issue: an email, phone or ZIP code is not in a valid form.

    #### PAYMENTS_DO_NOT_SUM

    HTTP 422. Retry the same request: no.

    > The payments must add up to the Net Amount Due to the cent. Change the payment amounts so they match.

    When: A validation issue: the payments do not add up to the Net Amount Due.

    #### PAYMENT_ONE_TOO_HIGH

    HTTP 422. Retry the same request: no.

    > Payment 1 (due at signing) may be at most the lower of $1,000 ($500 in New York and New Jersey) and 10% of the Net Amount Due. Lower Payment 1 and move the rest to a later payment.

    When: A validation issue: Payment 1 is above the lower of $1,000 ($500 in NY and NJ) and 10% of the Net Amount Due.

    #### PAYMENT_EXCEEDS_NET_AMOUNT_DUE

    HTTP 422. Retry the same request: no.

    > A payment is larger than the Net Amount Due. Lower it.

    When: A validation issue: one payment is larger than the Net Amount Due.

    #### ADDITIONAL_PRODUCT_EXCEEDS_EPC

    HTTP 422. Retry the same request: no.

    > An additional product amount is larger than the EPC amount. Check the amount; it is in USD.

    When: A validation issue: a selected additional product costs more than the EPC.

    #### PTO_BEFORE_INSTALL

    HTTP 422. Retry the same request: no.

    > The forecasted PTO date must be after the forecasted install start date. Send sales.ptoDate later than sales.installStartDate.

    When: A validation issue: the forecasted PTO date is on or before the forecasted install start date.

    #### INSTALL_BEFORE_CONTRACT

    HTTP 422. Retry the same request: no.

    > The forecasted install start date cannot be before the contract date. Send sales.installStartDate on or after sales.contractDate.

    When: A validation issue: the forecasted install start date (`sales.installStartDate`) is before the contract date.

    #### MILESTONE_NAME_INVALID

    HTTP 422. Retry the same request: no.

    > Each payment milestone name must be 5 to 30 characters. Rename the milestone the issue names.

    When: A validation issue: a payment milestone name is shorter than 5 or longer than 30 characters.

    #### COSIGNER_EMAIL_SAME_AS_CUSTOMER

    HTTP 422. Retry the same request: no.

    > The cosigner email must differ from the customer email: each signer gets their own signing link. Send the cosigner's own email.

    When: A validation issue: the cosigner and the customer have the same email.

    #### COSIGNER_NOT_SUPPORTED

    HTTP 422. Retry the same request: no.

    > The customer agreement for this state has no place for a cosigner to sign. Remove the cosigner (cosigner: null), or ask Participate Energy to add a cosigner signature to the agreement.

    When: A validation issue: the draft has a cosigner and the state's customer agreement has no cosigner signature (`contractTemplate.cosignerAllowed` is false in `GET /contract-drafts/defaults`). The send refuses the same draft with `CONTRACT_NOT_SENDABLE` before anything is created.

    #### CONTRACT_DATA_MISSING

    HTTP 422. Retry the same request: no.

    > The customer agreement needs a value that does not come from the draft (it is read from your organization's settings or Participate Energy's records). The issue names it. Ask Participate Energy at raceway.support@participate.energy.

    When: A validation issue: filled from the project the send would create, the customer agreement (or a document PE attaches to it) would leave a mandatory field blank, and no draft field fills it: the value comes from your company's settings or PE's records. The message names the field by its label. `field` is empty.

    #### EQUIPMENT_MANUFACTURER_MISMATCH

    HTTP 422. Retry the same request: no.

    > The inverter and battery manufacturers differ. Confirm the pairing with system.confirmManufacturerMismatch: true, or change the equipment.

    When: A validation issue: on a system with a battery, the inverter and battery manufacturers differ and the pairing is not confirmed.

    #### EQUIPMENT_NOT_FOR_SYSTEM_TYPE

    HTTP 422. Retry the same request: no.

    > The equipment does not fit the system type: a Solar Only system has no battery. Send systemType PV+Storage, or leave the battery out.

    When: A validation issue: a Solar Only draft has a battery line (`field` names it), or a Solar Only draft's values hold a battery.

    #### PRICING_NOT_CALCULATED

    HTTP 422. Retry the same request: no.

    > The lease price of the draft has not been calculated yet. The issue lists the pricing inputs to send.

    When: A validation issue: the lease price could not be calculated yet. The message lists the missing pricing inputs, or says that a pricing lookup was unavailable.

    #### PRICING_STALE

    HTTP 422. Retry the same request: no.

    > A pricing input changed after the lease price was calculated (for example in the Installer Portal). Update the draft with PATCH so the price is calculated again.

    When: A validation issue: a pricing input changed after the price was calculated, for example when the rep edited the draft in the portal.

    #### AUTO_SIGNER_REQUIRED

    HTTP 422. Retry the same request: no.

    > Nobody at your company is set up to sign the customer agreement automatically, so it cannot be sent. {reason} Ask your administrator to set up a default signer in E-sign Setup in the Installer Portal, then send again.

    When: Your company has no default signer for the customer agreement of the state, so the installer line cannot be signed. PE checks this before it creates the project. The message gives the reason (no signer, more than one signer and no default, or an agreement with fields to type at signing).

    #### CONTRACT_TEMPLATE_NOT_FOUND

    HTTP 422. Retry the same request: no.

    > There is no customer agreement ready for {stateCode} for your company yet, so the contract cannot be sent. Ask Participate Energy at raceway.support@participate.energy to publish one, then send again.

    When: PE has no published customer agreement for the site's state, the product and your contract type. PE checks this before it creates the project.

    #### CONTRACT_NOT_SENDABLE

    HTTP 422. Retry the same request: no.

    > Participate Energy could not send the contract: {reason} Fix the cause, then send again. When details name a projectId, the project was created; send its contract with POST /v2/installer/projects/<projectId>/contract-esign/send.

    When: The contract cannot be sent as it is: for example the agreement has no cosigner signature and the draft has a cosigner, a field the agreement needs is empty on the project, or the project's financials have to be balanced first. The message gives the reason. When `details` has a `projectId`, PE created the project and only the send is left.

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

    When: The key used its per-minute limit for this kind of call, or your IP address had too many failed authentications in one minute.

    The `Retry-After` header gives the seconds to wait. `details` gives `limit`, `window` and `resetAt`.

    #### DAILY_QUOTA_EXCEEDED

    HTTP 429. Retry the same request: yes.

    > Your company used its daily limit of {limit} {quota} in the {environment} environment. The limit resets at {resetAt}; retry after that.

    When: Your company used its daily limit of contract uploads or file uploads in this environment. The day is the UTC day.

    The `Retry-After` header gives the seconds until the limit resets. `details` gives `limit`, `used`, `requested` and `resetAt`.

    #### MONITORING_ACCESS_RATE_LIMITED

    HTTP 429. Retry the same request: yes.

    > Too many monitoring site saves on this project. {reason} Wait, then retry.

    When: The project had too many monitoring site saves in a short time.

    ### HTTP 500 to 504: server and service errors

    #### NOT_IMPLEMENTED

    HTTP 501. Retry the same request: no.

    > This endpoint is not available yet. See https://api.participate.energy/docs/installer/v2/ for the endpoints that work today.

    When: Reserved. PE returns it only if an endpoint in this reference is not turned on in the deployed API. You should not see it. Contact PE if you do.

    #### NOT_YET_AVAILABLE

    HTTP 501. Retry the same request: no.

    > This feature is not available in the Installer API yet. See https://api.participate.energy/docs/installer/v2/ for the endpoints that work today.

    When: PE does not return this code today. It is kept for a feature that PE announces before it is turned on.

    #### CONTRACT_SEND_FAILED

    HTTP 502. Retry the same request: yes.

    > The contract for project {projectId} could not be sent because of an error at Participate Energy. The project exists. Retry the send in a few minutes with POST /v2/installer/projects/{projectId}/contract-esign/send.

    When: PE created the project but an error at PE stopped the e-sign send. `details` has the `projectId`. Send again in a few minutes; PE does not create the project twice.

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

    When: A service that the request depends on did not answer in time.

    #### SERVICE_DISABLED

    HTTP 503. Retry the same request: yes.

    > The Installer API is turned off for now by Participate Energy. Retry later, or ask raceway.support@participate.energy for the status.

    When: PE turned off the Installer API for everyone, for example during an incident.

    #### INTERNAL_ERROR

    HTTP 500. Retry the same request: yes.

    > An unexpected error occurred while handling request {requestId}. Retry after waits of 1, 2, 4, 8 and 16 seconds, and stop after 5 tries. If it still fails, send the request id to raceway.support@participate.energy.

    When: PE had an unexpected error. The message quotes the request id.

    #### 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 where the endpoint allows it.

    When: The Energy Community data service did not answer.

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

    When: The sales tax rate service did not answer.

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

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

    #### SUNGAGE_UNAVAILABLE

    HTTP 503. Retry the same request: yes.

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

    When: Sungage did not answer.

    #### STATE_FIELDS_UNAVAILABLE

    HTTP 503. Retry the same request: yes.

    > The {stateCode} contract fields could not be read right now, so nothing was saved or checked. Retry the same request in a few minutes.

    When: PE could not read the state's contract fields (the ones your Participate Energy administrator defines for the state) while it built or checked a contract draft (`POST /contract-drafts`, `PATCH /contract-drafts/{draftId}`, `POST /contract-drafts/{draftId}/validate`, `GET /contract-drafts/defaults`). Nothing was saved, and the draft keeps every state field value it had. Send the same request again in a few minutes.
  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/installer
    description: Test and production. The key selects the environment.
security:
  - bearerAuth: []
tags:
  - name: Meta
    description: Check the key and read your account facts and limits.
  - name: Reference
    description: "PE's reference data: the AVL, your Safe Harbor opportunities, utilities, your states, your Equipment Map and the reference lists. Production data in both environments."
  - name: Eligibility
    description: Check a site, Domestic Content, Energy Community and the lease sales tax rate before you price.
  - name: Pricing
    description: Price a PE lease, or a PE lease with a Sungage loan. A quote never creates a project.
  - name: Contract uploads
    description: "Create a project by uploading the signed customer agreement: create, PUT the PDF, submit, poll."
  - name: Contract drafts
    description: "Prefill Contract Builder drafts for your sales reps: create, read, update, validate and delete (scope contracts:write), and send one for e-signature (scope contracts:send)."
  - name: Contract e-sign
    description: "The contract of a project: read its e-sign status and signers, send it again or void it."
  - name: Projects
    description: List and read your projects, and change what the Installer Portal lets you change.
  - name: Documents
    description: "The document slots of a project: versions, review status, automated review results, uploads, archive and restore."
  - name: Photos
    description: The photo categories of a project and photo uploads.
  - name: Monitoring access
    description: The monitoring site IDs of a project and PE's check of each site.
  - name: Actions
    description: The issues PE raised on a project. Read them, add notes and resolve them.
  - name: Webhooks
    description: Your webhook URL and signing secret, the IC and PC approval events, the new Action events and the contract status events.
  - name: Sandbox
    description: "Test keys only: the contract upload scenarios and simulated PE events."
paths:
  /ping:
    get:
      operationId: ping
      tags:
        - Meta
      summary: Check the key
      description: |-
        Check that your key works. The response shows the environment, your company, the grant id and the scopes of the key. Call it after you install a new key, and when a call fails for an unknown reason.

        **Scope:** none. **X-PE-Actor-Email:** optional.

        **Errors:** the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PingResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      ok: true
                      environment: test
                      installer:
                        name: Sunbright Solar (example)
                      grantId: igr_4bT9xQ2mK7pL1sV8nR3c
                      keyPrefix: ik_test_Ab3dE6
                      scopes:
                        - avl:read
                        - projects:read
                      serverTime: "2026-11-11T18:02:11.482Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth: []
      x-pe-scope: null
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /me:
    get:
      operationId: getMe
      tags:
        - Meta
      summary: Read your account
      description: |-
        Read your company's account facts: active states, enabled products, Sungage enrollment, the enabled environments and the rate limits for this key.

        **Scope:** none. **X-PE-Actor-Email:** optional.

        **Errors:** the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MeResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      installer:
                        name: Sunbright Solar (example)
                      environment: live
                      grantId: igr_4bT9xQ2mK7pL1sV8nR3c
                      keyPrefix: ik_live_Xy7pQ2
                      scopes:
                        - avl:read
                        - projects:read
                        - projects:write
                      activeStates:
                        - stateCode: CA
                          name: California
                        - stateCode: TX
                          name: Texas
                      productTypes:
                        - Synthetic Cash
                      apiContractUploadProducts:
                        - Synthetic Cash
                      sungage:
                        enrolled: false
                      environments:
                        test: true
                        live: true
                      rateLimits:
                        readsPerMinute: 120
                        writesPerMinute: 60
                        pricingPerMinute: 60
                        uploadsPerMinute: 30
                        contractUploadsPerDay: 200
                        fileUploadsPerDay: 2000
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth: []
      x-pe-scope: null
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /avl:
    get:
      operationId: listAvl
      tags:
        - Reference
      summary: List AVL equipment
      description: |-
        List the items on PE's Approved Vendor List (AVL) with their Domestic Content values. Every piece of equipment on a PE project must be on the AVL.

        Filter by `category`, `manufacturer` (contains) and `q` (searches the SKU, manufacturer and display strings). The AVL changes as one list: PE publishes a new version. Send `updatedSince` to check for a new version. PE compares it with the time the current version became active. When the version is not newer, the page is empty and `unchangedSince` is `true`. When PE does not know the activation time, it returns the full list with `updatedSinceApplied: false`. A cursor works only for the AVL version that issued it.

        **Scope:** `avl:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`CURSOR_INVALID`](#error-CURSOR_INVALID).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: category
          in: query
          required: false
          description: Only items of this category.
          schema:
            $ref: "#/components/schemas/AvlCategory"
        - name: manufacturer
          in: query
          required: false
          description: Manufacturer contains this text (any case).
          schema:
            type: string
            minLength: 1
            maxLength: 100
        - name: q
          in: query
          required: false
          description: Search text.
          schema:
            type: string
            minLength: 1
            maxLength: 100
        - name: updatedSince
          in: query
          required: false
          description: YYYY-MM-DD or an ISO 8601 timestamp.
          schema:
            type: string
            maxLength: 40
        - name: limit
          in: query
          required: false
          description: Page size, 1 to 500. Default 100.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: cursor
          in: query
          required: false
          description: The nextCursor of the previous page. Send the same filters.
          schema:
            type: string
            maxLength: 200
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AvlPageResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      avlVersion:
                        number: 42
                        label: AVL 2026-11
                        uploadedAt: "2026-11-01T16:00:00.000Z"
                      total: 1
                      items:
                        - avlItemId: avl_8Hc2Kd91LmQ4
                          sku: Q.TRON BLK M-G2+ 430
                          category: pv_module
                          manufacturer: Qcells
                          model: 430W
                          description: Qcells - Q.TRON BLK M-G2+ 430
                          domesticContent:
                            moduleDC: 0.42
                      nextCursor: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, VALIDATION_FAILED, UNKNOWN_FIELD, CURSOR_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                CURSOR_INVALID:
                  $ref: "#/components/examples/Error_CURSOR_INVALID"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /avl/{itemId}:
    get:
      operationId: getAvlItem
      tags:
        - Reference
      summary: Read an AVL item
      description: |-
        Read one AVL item by its `avlItemId`.

        **Scope:** `avl:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: itemId
          in: path
          required: true
          description: The AVL item id (avlItemId).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AvlItemResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      avlItemId: avl_8Hc2Kd91LmQ4
                      sku: Q.TRON BLK M-G2+ 430
                      category: pv_module
                      manufacturer: Qcells
                      model: 430W
                      description: Qcells - Q.TRON BLK M-G2+ 430
                      domesticContent:
                        moduleDC: 0.42
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /safe-harbor/opportunities:
    get:
      operationId: listSafeHarborOpportunities
      tags:
        - Reference
      summary: List Safe Harbor opportunities
      description: |-
        List your company's Safe Harbor opportunities with their status and units. `usableForPricing` is true when pricing can take a deduction from the opportunity (Strategy D, active, with a unit cost).

        **Scope:** `avl:read`. **X-PE-Actor-Email:** optional.

        **Errors:** the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SafeHarborOpportunityListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      opportunities:
                        - opportunityId: SHO-0042
                          name: 2025 Module Program
                          programCode: SH25M
                          strategy: D
                          status: active
                          bocDate: "2025-06-30"
                          unitCost: 4.68
                          unitsTotal: 2000
                          unitsConsumed: 120
                          unitsAvailable: 1880
                          usableForPricing: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /safe-harbor/opportunities/{opportunityId}:
    get:
      operationId: getSafeHarborOpportunity
      tags:
        - Reference
      summary: Read a Safe Harbor opportunity
      description: |-
        Read one of your opportunities with its custom AVL. A project with equipment that matches the custom AVL uses its Domestic Content values.

        **Scope:** `avl:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND), [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: opportunityId
          in: path
          required: true
          description: The Safe Harbor opportunity id.
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SafeHarborOpportunityDetailResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      opportunityId: SHO-0042
                      name: 2025 Module Program
                      programCode: SH25M
                      strategy: D
                      status: active
                      bocDate: "2025-06-30"
                      unitCost: 4.68
                      unitsTotal: 2000
                      unitsConsumed: 120
                      unitsAvailable: 1880
                      usableForPricing: true
                      customAvl:
                        - skuPattern: Q.TRON BLK M-G2+ 4*
                          category: pv_module
                          manufacturer: Qcells
                          product: Q.TRON BLK M-G2+
                          typeRef: null
                          domesticContent:
                            moduleDC: 0.55
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: SAFE_HARBOR_OPPORTUNITY_NOT_FOUND, RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /utilities:
    get:
      operationId: listUtilities
      tags:
        - Reference
      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 eligibility checks and as `utility.name` in `PATCH /projects/{projectId}`.

        `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`. **X-PE-Actor-Email:** optional.

        **Errors:** the common errors listed in Errors.
      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.
          schema:
            type: string
            pattern: ^[0-9]{5}(-[0-9]{4})?$
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UtilityListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      zipCode: "78701"
                      stateCode: TX
                      utilities:
                        - name: Austin Energy
                          primary: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /states:
    get:
      operationId: listStates
      tags:
        - Reference
      summary: List your states
      description: |-
        List the states where your company is active and PE operates, and the PE products enabled for your company. Request a new state in the Installer Portal.

        **Scope:** `avl:read`. **X-PE-Actor-Email:** optional.

        **Errors:** the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StateListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      states:
                        - stateCode: CA
                          name: California
                        - stateCode: TX
                          name: Texas
                      enabledProducts:
                        - Synthetic Cash
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /equipment-map:
    get:
      operationId: getEquipmentMap
      tags:
        - Reference
      summary: Read your Equipment Map
      description: |-
        Read your Equipment Map: the equipment strings your company used, and the AVL item each one resolves to. `PUT /projects/{projectId}/equipment` accepts a string from this map by `name`.

        **Scope:** `avl:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`CURSOR_INVALID`](#error-CURSOR_INVALID).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: category
          in: query
          required: false
          description: Only entries of this AVL category.
          schema:
            $ref: "#/components/schemas/AvlCategory"
        - name: field
          in: query
          required: false
          description: Only entries for this equipment field.
          schema:
            type: string
            enum:
              - moduleSku
              - inverterSku
              - rackingPartNumber
              - storageLeadUnitPartNumber
              - storageExpansionUnitPartNumber
              - pvComboModInverter
        - name: q
          in: query
          required: false
          description: The string contains this text.
          schema:
            type: string
            minLength: 1
            maxLength: 100
        - name: limit
          in: query
          required: false
          description: Page size, 1 to 500. Default 200.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 200
        - name: cursor
          in: query
          required: false
          description: The nextCursor of the previous page. Send the same filters.
          schema:
            type: string
            maxLength: 200
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EquipmentMapPageResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      entries:
                        - rawValue: QCELLS 430 BLK
                          field: moduleSku
                          category: pv_module
                          status: certified
                          certified: true
                          certifiedAt: "2026-09-12T15:00:00.000Z"
                          resolves: true
                          avlItem:
                            avlItemId: avl_8Hc2Kd91LmQ4
                            sku: Q.TRON BLK M-G2+ 430
                            category: pv_module
                            manufacturer: Qcells
                            model: 430W
                            description: Qcells - Q.TRON BLK M-G2+ 430
                            domesticContent:
                              moduleDC: 0.42
                          suggestedAvlItem: null
                          matchCount: 14
                          lastSeenAt: "2026-11-03T19:00:00.000Z"
                      nextCursor: null
                      truncated: false
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, VALIDATION_FAILED, UNKNOWN_FIELD, CURSOR_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                CURSOR_INVALID:
                  $ref: "#/components/examples/Error_CURSOR_INVALID"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /reference:
    get:
      operationId: getReference
      tags:
        - Reference
      summary: Read the reference lists
      description: |-
        Read PE's reference lists with plain descriptions: insurance options, system types, home types, product types, the document types you can upload (with the IC or PC stage and when each is required), photo categories by system type, milestones, project statuses and Action statuses.

        **Scope:** `avl:read`. **X-PE-Actor-Email:** optional.

        **Errors:** the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReferenceResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      insuranceOptions:
                        - option: 1
                          projectValue: "1"
                          label: Homeowner's insurance, Participate Energy as loss payee
                          description: The customer's homeowner's insurance covers the system and names Participate Energy as loss payee.
                          riskAdjustmentRate: 0
                      systemTypes:
                        - value: solar_only
                          projectValue: Solar Only
                          label: Solar only
                          description: Solar panels with no battery.
                      homeTypes: []
                      productTypes: []
                      documentTypes:
                        - documentType: signedFinalPermit
                          label: Signed Final Permit
                          category: construction
                          stage: ic
                          stageLabel: Inspection Complete
                          required: true
                          blocksReview: true
                          whenRequired: Always.
                          uploadVia: documents
                      photos:
                        minimumFilesPerCategory: 1
                      milestones:
                        - value: Project Onboarded
                          description: The contract is accepted and the project exists.
                      projectStatuses: []
                      actionStatuses: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - avl:read
      x-pe-scope: avl:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /eligibility:
    post:
      operationId: checkEligibility
      tags:
        - Eligibility
      summary: Check site eligibility
      description: |-
        Run PE's eligibility rules on a site. Each rule is one entry in `checks`. 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.

        The checks: `state` (PE operates there), `installer_state` (your company is active there), `product` (the PE lease is enabled for you), `utility` (only when you send one), `home_type`, `ownership` and `existing_solar` (only when you send them), and `address` (found, in the US and in `stateCode`). PE also has rules the API cannot check, such as roof condition, roof type and HOA approval. PE checks them in its review.

        **Scope:** `eligibility:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US), [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX).
      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:
              example:
                summary: Example
                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: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EligibilityResponse"
              examples:
                example:
                  summary: Example
                  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: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ADDRESS_OUTSIDE_US:
                  $ref: "#/components/examples/Error_ADDRESS_OUTSIDE_US"
                ADDRESS_PO_BOX:
                  $ref: "#/components/examples/Error_ADDRESS_PO_BOX"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
        "504":
          description: "A service did not answer in time. Codes: UPSTREAM_TIMEOUT."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPSTREAM_TIMEOUT:
                  $ref: "#/components/examples/Error_UPSTREAM_TIMEOUT"
      security:
        - bearerAuth:
            - eligibility:read
      x-pe-scope: eligibility:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /checks/domestic-content:
    post:
      operationId: checkDomesticContent
      tags:
        - Eligibility
      summary: Check Domestic Content
      description: |-
        Check a list of equipment against the AVL and tell whether PV and storage meet the Domestic Content threshold. Add `safeHarborOpportunityId` to include that opportunity's custom AVL. A SKU that PE cannot match is listed in `unresolved`. The call fails only when no SKU matches. Use `pv` and `storage` for `pvDomesticContent` and `storageDomesticContent` in pricing. 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`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND), [`EQUIPMENT_NOT_ON_AVL`](#error-EQUIPMENT_NOT_ON_AVL), [`EQUIPMENT_AMBIGUOUS`](#error-EQUIPMENT_AMBIGUOUS), [`EQUIPMENT_CATEGORY_MISMATCH`](#error-EQUIPMENT_CATEGORY_MISMATCH), [`EQUIPMENT_QUANTITY_OUT_OF_RANGE`](#error-EQUIPMENT_QUANTITY_OUT_OF_RANGE).
      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:
              example:
                summary: Example
                value:
                  equipment:
                    - sku: Q.TRON BLK M-G2+ 430
                      category: pv_module
                      quantity: 20
                    - sku: IQ8M-72-2-US
                      category: pv_inverter
                      quantity: 20
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DomesticContentResponse"
              examples:
                example:
                  summary: Example
                  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: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: SAFE_HARBOR_OPPORTUNITY_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
          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"
                EQUIPMENT_CATEGORY_MISMATCH:
                  $ref: "#/components/examples/Error_EQUIPMENT_CATEGORY_MISMATCH"
                EQUIPMENT_QUANTITY_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EQUIPMENT_QUANTITY_OUT_OF_RANGE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
        "504":
          description: "A service did not answer in time. Codes: UPSTREAM_TIMEOUT."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPSTREAM_TIMEOUT:
                  $ref: "#/components/examples/Error_UPSTREAM_TIMEOUT"
      security:
        - bearerAuth:
            - eligibility:read
      x-pe-scope: eligibility:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /checks/energy-community:
    post:
      operationId: checkEnergyCommunity
      tags:
        - Eligibility
      summary: Check Energy Community
      description: |-
        Tell whether the site is in an Energy Community. Energy Community alone does not raise the lease factor. It prevents the 25% tier. You can also send `energyCommunity: "auto"` in a quote.

        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`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US), [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND), [`STATE_MISMATCH`](#error-STATE_MISMATCH), [`ADDRESS_LOOKUP_UNAVAILABLE`](#error-ADDRESS_LOOKUP_UNAVAILABLE), [`EC_LOOKUP_UNAVAILABLE`](#error-EC_LOOKUP_UNAVAILABLE), [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX).
      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:
              example:
                summary: Example
                value:
                  address:
                    street: 100 Example Street
                    city: Sacramento
                    stateCode: CA
                    zipCode: "95814"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnergyCommunityResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      qualifies: false
                      category: null
                      itcBonus: 0
                      countyFips: "06067"
                      tractGeoid: "06067001101"
                      resolvedAddress:
                        formatted: 100 Example St, Sacramento, CA 95814, USA
                        street: 100 Example St
                        city: Sacramento
                        stateCode: CA
                        zipCode: "95814"
                        county: Sacramento
                        latitude: 38.5816
                        longitude: -121.4944
                        precision: rooftop
                        partialMatch: false
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
          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"
                ADDRESS_PO_BOX:
                  $ref: "#/components/examples/Error_ADDRESS_PO_BOX"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "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"
          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"
        "504":
          description: "A service did not answer in time. Codes: UPSTREAM_TIMEOUT."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPSTREAM_TIMEOUT:
                  $ref: "#/components/examples/Error_UPSTREAM_TIMEOUT"
      security:
        - bearerAuth:
            - eligibility:read
      x-pe-scope: eligibility:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /checks/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.

        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`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US), [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND), [`STATE_MISMATCH`](#error-STATE_MISMATCH), [`SALES_TAX_UNRESOLVED`](#error-SALES_TAX_UNRESOLVED), [`TAX_RATE_UNAVAILABLE`](#error-TAX_RATE_UNAVAILABLE), [`ADDRESS_LOOKUP_UNAVAILABLE`](#error-ADDRESS_LOOKUP_UNAVAILABLE), [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX), [`AMOUNT_OUT_OF_RANGE`](#error-AMOUNT_OUT_OF_RANGE), [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED).
      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:
              example:
                summary: Example
                value:
                  address:
                    street: 200 Example Avenue
                    city: Austin
                    stateCode: TX
                    zipCode: "78701"
                  systemType: solar_only
                  netAmountDue: 21000
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SalesTaxCheckResponse"
              examples:
                example:
                  summary: Example
                  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-11"
                      note: null
                      resolvedAddress:
                        formatted: 200 Example Ave, Austin, TX 78701, USA
                        street: 200 Example Ave
                        city: Austin
                        stateCode: TX
                        zipCode: "78701"
                        county: Travis
                        latitude: 30.2672
                        longitude: -97.7431
                        precision: rooftop
                        partialMatch: false
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
          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"
                ADDRESS_PO_BOX:
                  $ref: "#/components/examples/Error_ADDRESS_PO_BOX"
                AMOUNT_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_AMOUNT_OUT_OF_RANGE"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "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"
          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"
        "504":
          description: "A service did not answer in time. Codes: UPSTREAM_TIMEOUT."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPSTREAM_TIMEOUT:
                  $ref: "#/components/examples/Error_UPSTREAM_TIMEOUT"
      security:
        - bearerAuth:
            - eligibility:read
      x-pe-scope: eligibility:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /pricing/lease:
    post:
      operationId: priceLease
      tags:
        - Pricing
      summary: Price a PE lease
      description: |-
        Price a PE lease. The API runs the same calculation as the Lease Value Calculator in the Installer Portal. See How PE prices a lease. A quote never creates a project.

        Send `basis: "netAmountDue"` with `targetNetAmountDue` (and no `epcAmount`) to solve the EPC from the customer's price. A state where your company is not active yet still prices, with a `STATE_NOT_ACTIVE_FOR_INSTALLER` warning.

        **Scope:** `pricing:lease`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US), [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND), [`STATE_MISMATCH`](#error-STATE_MISMATCH), [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED), [`EPC_OUT_OF_RANGE`](#error-EPC_OUT_OF_RANGE), [`NET_AMOUNT_DUE_OUT_OF_RANGE`](#error-NET_AMOUNT_DUE_OUT_OF_RANGE), [`ROOFING_COST_INVALID`](#error-ROOFING_COST_INVALID), [`INCENTIVE_NOT_AVAILABLE`](#error-INCENTIVE_NOT_AVAILABLE), [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND), [`SAFE_HARBOR_UNITS_INVALID`](#error-SAFE_HARBOR_UNITS_INVALID), [`SALES_TAX_UNRESOLVED`](#error-SALES_TAX_UNRESOLVED), [`TAX_RATE_UNAVAILABLE`](#error-TAX_RATE_UNAVAILABLE), [`EC_LOOKUP_UNAVAILABLE`](#error-EC_LOOKUP_UNAVAILABLE), [`EPC_PER_WATT_OUT_OF_RANGE`](#error-EPC_PER_WATT_OUT_OF_RANGE), [`CONTRACT_DATE_OUT_OF_RANGE`](#error-CONTRACT_DATE_OUT_OF_RANGE), [`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`](#error-CONTRACT_DATE_BEFORE_RETITC_CUTOFF), [`INCENTIVE_OUT_OF_RANGE`](#error-INCENTIVE_OUT_OF_RANGE), [`ROOFING_COST_NOT_APPLICABLE`](#error-ROOFING_COST_NOT_APPLICABLE), [`SYSTEM_SIZE_LOOKS_LIKE_WATTS`](#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS), [`SYSTEM_SIZE_OUT_OF_RANGE`](#error-SYSTEM_SIZE_OUT_OF_RANGE), [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX).
      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:
              example:
                summary: Example
                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"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeasePriceQuoteResponse"
              examples:
                example:
                  summary: Example
                  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: []
                      basis: epc
                      epcAmount: 42000
                      targetNetAmountDue: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: SAFE_HARBOR_OPPORTUNITY_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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, STATE_NOT_SUPPORTED, EPC_OUT_OF_RANGE, NET_AMOUNT_DUE_OUT_OF_RANGE, ROOFING_COST_INVALID, INCENTIVE_NOT_AVAILABLE, SAFE_HARBOR_UNITS_INVALID, SALES_TAX_UNRESOLVED, EPC_PER_WATT_OUT_OF_RANGE, CONTRACT_DATE_OUT_OF_RANGE, CONTRACT_DATE_BEFORE_RETITC_CUTOFF, INCENTIVE_OUT_OF_RANGE, ROOFING_COST_NOT_APPLICABLE, SYSTEM_SIZE_LOOKS_LIKE_WATTS, SYSTEM_SIZE_OUT_OF_RANGE, ADDRESS_PO_BOX."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
                EPC_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EPC_OUT_OF_RANGE"
                NET_AMOUNT_DUE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_NET_AMOUNT_DUE_OUT_OF_RANGE"
                ROOFING_COST_INVALID:
                  $ref: "#/components/examples/Error_ROOFING_COST_INVALID"
                INCENTIVE_NOT_AVAILABLE:
                  $ref: "#/components/examples/Error_INCENTIVE_NOT_AVAILABLE"
                SAFE_HARBOR_UNITS_INVALID:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_UNITS_INVALID"
                SALES_TAX_UNRESOLVED:
                  $ref: "#/components/examples/Error_SALES_TAX_UNRESOLVED"
                EPC_PER_WATT_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EPC_PER_WATT_OUT_OF_RANGE"
                CONTRACT_DATE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_CONTRACT_DATE_OUT_OF_RANGE"
                INCENTIVE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_INCENTIVE_OUT_OF_RANGE"
                ROOFING_COST_NOT_APPLICABLE:
                  $ref: "#/components/examples/Error_ROOFING_COST_NOT_APPLICABLE"
                SYSTEM_SIZE_LOOKS_LIKE_WATTS:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_LOOKS_LIKE_WATTS"
                SYSTEM_SIZE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_OUT_OF_RANGE"
                ADDRESS_PO_BOX:
                  $ref: "#/components/examples/Error_ADDRESS_PO_BOX"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "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"
          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"
        "504":
          description: "A service did not answer in time. Codes: UPSTREAM_TIMEOUT."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPSTREAM_TIMEOUT:
                  $ref: "#/components/examples/Error_UPSTREAM_TIMEOUT"
      security:
        - bearerAuth:
            - pricing:lease
      x-pe-scope: pricing:lease
      x-pe-rate-limit-bucket: pricing
      x-pe-actor: optional
  /pricing/sungage/products:
    get:
      operationId: listSungageProducts
      tags:
        - Pricing
      summary: List Sungage products
      description: |-
        List the Sungage products, terms and rates for a state. `isPrepaidTpoState` is false where Sungage's prepaid program is not available, and `products` is then empty. Send `X-PE-Actor-Email`: PE sends it to Sungage as the user.

        **Scope:** `pricing:sungage`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`SUNGAGE_NOT_ENROLLED`](#error-SUNGAGE_NOT_ENROLLED), [`SUNGAGE_USER_NOT_REGISTERED`](#error-SUNGAGE_USER_NOT_REGISTERED), [`SUNGAGE_UNAVAILABLE`](#error-SUNGAGE_UNAVAILABLE), [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: stateCode
          in: query
          required: true
          description: 2-letter US state code.
          schema:
            type: string
            pattern: ^[A-Za-z]{2}$
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SungageProductsResponse"
              examples:
                example:
                  summary: Example
                  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-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, SUNGAGE_NOT_ENROLLED, SUNGAGE_USER_NOT_REGISTERED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "422":
          description: "The request breaks a rule. Codes: STATE_NOT_SUPPORTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED, SUNGAGE_UNAVAILABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
        "504":
          description: "A service did not answer in time. Codes: UPSTREAM_TIMEOUT."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPSTREAM_TIMEOUT:
                  $ref: "#/components/examples/Error_UPSTREAM_TIMEOUT"
      security:
        - bearerAuth:
            - pricing:sungage
      x-pe-scope: pricing:sungage
      x-pe-rate-limit-bucket: pricing
      x-pe-actor: required
  /pricing/sungage:
    post:
      operationId: priceSungage
      tags:
        - Pricing
      summary: Price a PE lease with a Sungage loan
      description: |-
        Price a PE lease with a Sungage loan. The body is the lease request plus `dppProduct`, `term` and `rate` from `GET /pricing/sungage/products`. The response has the lease block (`lease`), the loan, your payments and the totals. If Sungage cannot quote a monthly payment, `loan.estimatedMonthlyPayment` is null and `loan.paymentsNote` explains it. When `pricingChecksPassed` is false, do not use the quote and contact PE.

        **Scope:** `pricing:sungage`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`SUNGAGE_NOT_ENROLLED`](#error-SUNGAGE_NOT_ENROLLED), [`SUNGAGE_USER_NOT_REGISTERED`](#error-SUNGAGE_USER_NOT_REGISTERED), [`SUNGAGE_PRODUCT_UNAVAILABLE`](#error-SUNGAGE_PRODUCT_UNAVAILABLE), [`SUNGAGE_UNAVAILABLE`](#error-SUNGAGE_UNAVAILABLE), [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US), [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND), [`STATE_MISMATCH`](#error-STATE_MISMATCH), [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED), [`EPC_OUT_OF_RANGE`](#error-EPC_OUT_OF_RANGE), [`ROOFING_COST_INVALID`](#error-ROOFING_COST_INVALID), [`INCENTIVE_NOT_AVAILABLE`](#error-INCENTIVE_NOT_AVAILABLE), [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND), [`SAFE_HARBOR_UNITS_INVALID`](#error-SAFE_HARBOR_UNITS_INVALID), [`SALES_TAX_UNRESOLVED`](#error-SALES_TAX_UNRESOLVED), [`TAX_RATE_UNAVAILABLE`](#error-TAX_RATE_UNAVAILABLE), [`EC_LOOKUP_UNAVAILABLE`](#error-EC_LOOKUP_UNAVAILABLE), [`EPC_PER_WATT_OUT_OF_RANGE`](#error-EPC_PER_WATT_OUT_OF_RANGE), [`CONTRACT_DATE_OUT_OF_RANGE`](#error-CONTRACT_DATE_OUT_OF_RANGE), [`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`](#error-CONTRACT_DATE_BEFORE_RETITC_CUTOFF), [`INCENTIVE_OUT_OF_RANGE`](#error-INCENTIVE_OUT_OF_RANGE), [`ROOFING_COST_NOT_APPLICABLE`](#error-ROOFING_COST_NOT_APPLICABLE), [`SYSTEM_SIZE_LOOKS_LIKE_WATTS`](#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS), [`SYSTEM_SIZE_OUT_OF_RANGE`](#error-SYSTEM_SIZE_OUT_OF_RANGE), [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX).
      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:
              example:
                summary: Example
                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: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SungageQuoteResponse"
              examples:
                example:
                  summary: Example
                  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-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, SUNGAGE_NOT_ENROLLED, SUNGAGE_USER_NOT_REGISTERED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: SAFE_HARBOR_OPPORTUNITY_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: SUNGAGE_PRODUCT_UNAVAILABLE, ADDRESS_OUTSIDE_US, ADDRESS_NOT_FOUND, STATE_MISMATCH, STATE_NOT_SUPPORTED, EPC_OUT_OF_RANGE, ROOFING_COST_INVALID, INCENTIVE_NOT_AVAILABLE, SAFE_HARBOR_UNITS_INVALID, SALES_TAX_UNRESOLVED, EPC_PER_WATT_OUT_OF_RANGE, CONTRACT_DATE_OUT_OF_RANGE, CONTRACT_DATE_BEFORE_RETITC_CUTOFF, INCENTIVE_OUT_OF_RANGE, ROOFING_COST_NOT_APPLICABLE, SYSTEM_SIZE_LOOKS_LIKE_WATTS, SYSTEM_SIZE_OUT_OF_RANGE, ADDRESS_PO_BOX."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SUNGAGE_PRODUCT_UNAVAILABLE:
                  $ref: "#/components/examples/Error_SUNGAGE_PRODUCT_UNAVAILABLE"
                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"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
                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"
                SAFE_HARBOR_UNITS_INVALID:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_UNITS_INVALID"
                SALES_TAX_UNRESOLVED:
                  $ref: "#/components/examples/Error_SALES_TAX_UNRESOLVED"
                EPC_PER_WATT_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EPC_PER_WATT_OUT_OF_RANGE"
                CONTRACT_DATE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_CONTRACT_DATE_OUT_OF_RANGE"
                INCENTIVE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_INCENTIVE_OUT_OF_RANGE"
                ROOFING_COST_NOT_APPLICABLE:
                  $ref: "#/components/examples/Error_ROOFING_COST_NOT_APPLICABLE"
                SYSTEM_SIZE_LOOKS_LIKE_WATTS:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_LOOKS_LIKE_WATTS"
                SYSTEM_SIZE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_OUT_OF_RANGE"
                ADDRESS_PO_BOX:
                  $ref: "#/components/examples/Error_ADDRESS_PO_BOX"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          description: "A service is unavailable. Codes: SERVICE_DISABLED, SUNGAGE_UNAVAILABLE, TAX_RATE_UNAVAILABLE, EC_LOOKUP_UNAVAILABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                TAX_RATE_UNAVAILABLE:
                  $ref: "#/components/examples/Error_TAX_RATE_UNAVAILABLE"
                EC_LOOKUP_UNAVAILABLE:
                  $ref: "#/components/examples/Error_EC_LOOKUP_UNAVAILABLE"
        "504":
          description: "A service did not answer in time. Codes: UPSTREAM_TIMEOUT."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UPSTREAM_TIMEOUT:
                  $ref: "#/components/examples/Error_UPSTREAM_TIMEOUT"
      security:
        - bearerAuth:
            - pricing:sungage
      x-pe-scope: pricing:sungage
      x-pe-rate-limit-bucket: pricing
      x-pe-actor: required
  /contract-uploads:
    post:
      operationId: createContractUpload
      tags:
        - Contract uploads
      summary: Create a contract upload
      description: |-
        Start a contract upload. The response has a signed `uploadUrl` that is valid for 15 minutes. PUT the PDF to it with every header in `uploadHeaders`, then call submit. See Contract uploads.

        PE checks your company first: it is an install partner, it is not on hold, it is active in `stateCode`, and Synthetic Cash is enabled. The API creates Synthetic Cash projects only; upload Distributed Microgrid contracts in the Installer Portal. Each call counts toward the daily contract upload limit.

        **Scope:** `projects:create`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`SANDBOX_FIELD_IN_LIVE`](#error-SANDBOX_FIELD_IN_LIVE), [`SANDBOX_SCENARIO_INVALID`](#error-SANDBOX_SCENARIO_INVALID), [`INSTALLER_NOT_ELIGIBLE`](#error-INSTALLER_NOT_ELIGIBLE), [`INSTALLER_ON_HOLD`](#error-INSTALLER_ON_HOLD), [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED), [`STATE_NOT_ACTIVE_FOR_INSTALLER`](#error-STATE_NOT_ACTIVE_FOR_INSTALLER), [`PRODUCT_NOT_ENABLED`](#error-PRODUCT_NOT_ENABLED), [`PRODUCT_NOT_SUPPORTED_BY_API`](#error-PRODUCT_NOT_SUPPORTED_BY_API), [`PRODUCT_NOT_AVAILABLE_IN_STATE`](#error-PRODUCT_NOT_AVAILABLE_IN_STATE), [`EXTERNAL_ID_IN_USE`](#error-EXTERNAL_ID_IN_USE), [`DAILY_QUOTA_EXCEEDED`](#error-DAILY_QUOTA_EXCEEDED).
      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/CreateContractUploadRequest"
            examples:
              example:
                summary: Example
                value:
                  stateCode: CA
                  externalId: crm-10442
                  salesRep:
                    name: Riley Rep
                    email: riley@installer.example
                  fileName: jordan-example-agreement.pdf
                  sandboxScenario: project_created
      responses:
        "201":
          description: Created.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedContractUploadResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      uploadId: iup_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      uploadUrl: https://storage.googleapis.com/...?X-Goog-Signature=...
                      uploadHeaders:
                        Content-Type: application/pdf
                        x-goog-if-generation-match: "0"
                        x-goog-content-length-range: 0,26214400
                      expiresAt: "2026-11-11T18:17:11.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD, SANDBOX_FIELD_IN_LIVE, SANDBOX_SCENARIO_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
                SANDBOX_FIELD_IN_LIVE:
                  $ref: "#/components/examples/Error_SANDBOX_FIELD_IN_LIVE"
                SANDBOX_SCENARIO_INVALID:
                  $ref: "#/components/examples/Error_SANDBOX_SCENARIO_INVALID"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, INSTALLER_ON_HOLD, STATE_NOT_ACTIVE_FOR_INSTALLER, PRODUCT_NOT_ENABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                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"
        "409":
          description: "Conflict with the current state. Codes: EXTERNAL_ID_IN_USE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                EXTERNAL_ID_IN_USE:
                  $ref: "#/components/examples/Error_EXTERNAL_ID_IN_USE"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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, PRODUCT_NOT_SUPPORTED_BY_API, PRODUCT_NOT_AVAILABLE_IN_STATE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
                PRODUCT_NOT_SUPPORTED_BY_API:
                  $ref: "#/components/examples/Error_PRODUCT_NOT_SUPPORTED_BY_API"
                PRODUCT_NOT_AVAILABLE_IN_STATE:
                  $ref: "#/components/examples/Error_PRODUCT_NOT_AVAILABLE_IN_STATE"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED, DAILY_QUOTA_EXCEEDED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            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":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:create
      x-pe-scope: projects:create
      x-pe-rate-limit-bucket: upload
      x-pe-actor: required
  /contract-uploads/{uploadId}/submit:
    post:
      operationId: submitContractUpload
      tags:
        - Contract uploads
      summary: Submit a contract upload
      description: |-
        Tell PE that the PDF is in place. PE checks that the file exists, is 25 MB or less and starts with `%PDF-`. In production the status is then `queued`; poll `GET /contract-uploads/{uploadId}`. In the Test environment the scenario applies at once and the response has the final status. If the submit fails with a 5xx error, send it again.

        **Scope:** `projects:create`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`UPLOAD_ALREADY_SUBMITTED`](#error-UPLOAD_ALREADY_SUBMITTED), [`UPLOAD_URL_EXPIRED`](#error-UPLOAD_URL_EXPIRED), [`UPLOAD_FILE_MISSING`](#error-UPLOAD_FILE_MISSING), [`UPLOAD_FILE_TOO_LARGE`](#error-UPLOAD_FILE_TOO_LARGE), [`UPLOAD_NOT_PDF`](#error-UPLOAD_NOT_PDF), [`UPLOAD_FILE_EMPTY`](#error-UPLOAD_FILE_EMPTY).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: uploadId
          in: path
          required: true
          description: The contract upload id (iup_...).
          schema:
            type: string
      responses:
        "202":
          description: Accepted.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmittedContractUploadResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      uploadId: iup_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      status: queued
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                INVALID_JSON:
                  $ref: "#/components/examples/Error_INVALID_JSON"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: UPLOAD_ALREADY_SUBMITTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
          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"
          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"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: UPLOAD_FILE_MISSING, UPLOAD_NOT_PDF, UPLOAD_FILE_EMPTY."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                UPLOAD_FILE_EMPTY:
                  $ref: "#/components/examples/Error_UPLOAD_FILE_EMPTY"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:create
      x-pe-scope: projects:create
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /contract-uploads/{uploadId}:
    get:
      operationId: getContractUpload
      tags:
        - Contract uploads
      summary: Read a contract upload
      description: |-
        Read the status and outcome of a contract upload. Poll with backoff: wait 5 seconds, then double the wait up to 60 seconds. When `status` is `project_created`, `projectId` is the PE Project ID and `actions` lists its open Actions, in the same shape as `GET /projects/{projectId}/actions`.

        **Scope:** `projects:create`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: uploadId
          in: path
          required: true
          description: The contract upload id (iup_...).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractUploadResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      uploadId: iup_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      status: project_created
                      outcome: project_created
                      outcomeMessage: Participate Energy read the contract and created the project. Read it with GET /v2/installer/projects/SBX-CA2611-SAND1 and follow its Actions and approvals.
                      projectId: SBX-CA2611-SAND1
                      externalId: crm-10442
                      errors: []
                      actions: []
                      createdAt: "2026-11-11T18:02:11.000Z"
                      updatedAt: "2026-11-11T18:03:02.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:create
      x-pe-scope: projects:create
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /contract-esign:
    post:
      operationId: createContractEsign
      tags:
        - Contract e-sign
      summary: "Replaced: use the contract draft send"
      description: |-
        Replaced in 2.2: always returns `CONTRACT_ESIGN_MOVED` (410). Send a contract draft with `POST /contract-drafts/{draftId}/send`, or send the contract of an existing project again with `POST /projects/{projectId}/contract-esign/send`.

        **Scope:** `projects:create`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`CONTRACT_ESIGN_MOVED`](#error-CONTRACT_ESIGN_MOVED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, INVALID_JSON."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "410":
          description: "Gone. Codes: CONTRACT_ESIGN_MOVED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                CONTRACT_ESIGN_MOVED:
                  $ref: "#/components/examples/Error_CONTRACT_ESIGN_MOVED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:create
      x-pe-scope: projects:create
      x-pe-rate-limit-bucket: write
      x-pe-actor: optional
  /contract-drafts:
    get:
      operationId: listContractDrafts
      tags:
        - Contract drafts
      summary: List contract drafts
      description: |-
        Your API-created contract drafts in this environment, newest change first. Filter by `externalId` (one page, no cursor), `assignedToEmail` or `status`. The cursor is opaque. A page can be shorter than `limit` and still have a `nextCursor`: read on until it is null.

        **Scope:** `contracts:write`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`CURSOR_INVALID`](#error-CURSOR_INVALID).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: limit
          in: query
          required: false
          description: Page size, 1 to 100 (default 25).
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          required: false
          description: The nextCursor of the previous page.
          schema:
            type: string
        - name: externalId
          in: query
          required: false
          schema:
            type: string
        - name: assignedToEmail
          in: query
          required: false
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/ContractDraftStatus"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractDraftListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      drafts:
                        - draftId: cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                          status: draft
                          assignedTo:
                            email: riley@acme-solar.example
                            name: Riley Rep
                          externalId: crm-10442
                          label: Jordan Example (Sacramento, CA)
                          stateCode: CA
                          productType: Synthetic Cash
                          createdAt: "2026-11-12T18:02:11.482Z"
                          updatedAt: "2026-11-12T18:02:11.482Z"
                          body:
                            externalId: crm-10442
                            customer:
                              firstName: Jordan
                              lastName: Example
                              email: jordan@example.com
                              phone: 555-010-0199
                            siteAddress:
                              street: 100 Example Street
                              city: Sacramento
                              stateCode: CA
                              zipCode: "95814"
                            utility:
                              name: Pacific Gas & Electric
                            system:
                              systemType: Solar Only
                              annualUsageKwh: 10500
                              annualProductionKwh: 12000
                            equipment:
                              - category: module
                                avlItemId: avl_mod_123
                                quantity: 25
                              - category: inverter
                                avlItemId: avl_inv_456
                                quantity: 25
                              - category: racking
                                avlItemId: avl_rack_789
                            financials:
                              epcAmount: 32000
                              dcBonusRecipient: customer
                            stateFields:
                              utilityBillsUsed: "Yes"
                              preSolarTariff: E-TOU-C
                              postSolarTariff: E-ELEC
                              estimatedSavingsMaxBill: 1450
                          prefilledFields:
                            - financials.payments[1].name
                            - sales.installStartDate
                            - sales.ptoDate
                            - system.energySavingsCalculator
                          pricing:
                            quoteId: q_5Tn8Wc2Lx9Pr4Kd7
                            netAmountDue: 23680.36
                            leaseAmount: 23680.36
                            replacementCost: 32000
                            basis: epc
                            epcAmount: 32000
                            targetNetAmountDue: null
                          validation:
                            readyToSend: false
                            issues:
                              - step: financials
                                field: financials.payments
                                code: PAYMENTS_DO_NOT_SUM
                                message: The payments add up to $0.00 but the Net Amount Due is $23,680.36. They must match to the cent.
                                severity: error
                          warnings: []
                          portalUrl: https://raceway.participate.energy/projects/new?tab=drafts&draft=cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                          projectId: null
                          packetId: null
                      nextCursor: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, VALIDATION_FAILED, UNKNOWN_FIELD, CURSOR_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                CURSOR_INVALID:
                  $ref: "#/components/examples/Error_CURSOR_INVALID"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:write
      x-pe-scope: contracts:write
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
    post:
      operationId: createContractDraft
      tags:
        - Contract drafts
      summary: Create a contract draft
      description: |-
        Create a Contract Builder draft (a prefill) for one of your sales reps. PE starts from your prefill for the state, applies the body, prices the lease when the pricing inputs are complete and validates the draft with the builder's rules. With `?dryRun=true` nothing is saved and `draftId` is null. A live draft shows in the rep's Drafts tab; `portalUrl` opens it. See Contract drafts and e-sign.

        **Scope:** `contracts:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`ASSIGNEE_NOT_FOUND`](#error-ASSIGNEE_NOT_FOUND), [`ASSIGNEE_NOT_PERMITTED`](#error-ASSIGNEE_NOT_PERMITTED), [`PREFILL_LOCKED_FIELD`](#error-PREFILL_LOCKED_FIELD), [`EQUIPMENT_NOT_ALLOWED_BY_PREFILL`](#error-EQUIPMENT_NOT_ALLOWED_BY_PREFILL), [`PRODUCT_NOT_SUPPORTED_BY_API`](#error-PRODUCT_NOT_SUPPORTED_BY_API), [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX), [`EPC_OUT_OF_RANGE`](#error-EPC_OUT_OF_RANGE), [`SYSTEM_SIZE_LOOKS_LIKE_WATTS`](#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS), [`SYSTEM_SIZE_OUT_OF_RANGE`](#error-SYSTEM_SIZE_OUT_OF_RANGE), [`SYSTEM_SIZE_MISMATCH`](#error-SYSTEM_SIZE_MISMATCH), [`CONTRACT_DATE_OUT_OF_RANGE`](#error-CONTRACT_DATE_OUT_OF_RANGE), [`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`](#error-CONTRACT_DATE_BEFORE_RETITC_CUTOFF), [`EQUIPMENT_NOT_ON_AVL`](#error-EQUIPMENT_NOT_ON_AVL), [`EQUIPMENT_AMBIGUOUS`](#error-EQUIPMENT_AMBIGUOUS), [`EQUIPMENT_WRONG_CATEGORY`](#error-EQUIPMENT_WRONG_CATEGORY), [`INCENTIVE_NOT_AVAILABLE`](#error-INCENTIVE_NOT_AVAILABLE), [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED), [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND), [`PRODUCT_NOT_ENABLED`](#error-PRODUCT_NOT_ENABLED), [`EXTERNAL_ID_IN_USE`](#error-EXTERNAL_ID_IN_USE).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: dryRun
          in: query
          required: false
          description: "true: build and validate the draft without saving it."
          schema:
            type: string
            enum:
              - "true"
              - "false"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractDraftRequest"
            examples:
              example:
                summary: Example
                value:
                  externalId: crm-10442
                  customer:
                    firstName: Jordan
                    lastName: Example
                    email: jordan@example.com
                    phone: 555-010-0199
                  siteAddress:
                    street: 100 Example Street
                    city: Sacramento
                    stateCode: CA
                    zipCode: "95814"
                  utility:
                    name: Pacific Gas & Electric
                  system:
                    systemType: Solar Only
                    annualUsageKwh: 10500
                    annualProductionKwh: 12000
                  equipment:
                    - category: module
                      avlItemId: avl_mod_123
                      quantity: 25
                    - category: inverter
                      avlItemId: avl_inv_456
                      quantity: 25
                    - category: racking
                      avlItemId: avl_rack_789
                  financials:
                    epcAmount: 32000
                    dcBonusRecipient: customer
                  stateFields:
                    utilityBillsUsed: "Yes"
                    preSolarTariff: E-TOU-C
                    postSolarTariff: E-ELEC
                    estimatedSavingsMaxBill: 1450
      responses:
        "201":
          description: Created.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractDraftResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      draftId: cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      status: draft
                      assignedTo:
                        email: riley@acme-solar.example
                        name: Riley Rep
                      externalId: crm-10442
                      label: Jordan Example (Sacramento, CA)
                      stateCode: CA
                      productType: Synthetic Cash
                      createdAt: "2026-11-12T18:02:11.482Z"
                      updatedAt: "2026-11-12T18:02:11.482Z"
                      body:
                        externalId: crm-10442
                        customer:
                          firstName: Jordan
                          lastName: Example
                          email: jordan@example.com
                          phone: 555-010-0199
                        siteAddress:
                          street: 100 Example Street
                          city: Sacramento
                          stateCode: CA
                          zipCode: "95814"
                        utility:
                          name: Pacific Gas & Electric
                        system:
                          systemType: Solar Only
                          annualUsageKwh: 10500
                          annualProductionKwh: 12000
                        equipment:
                          - category: module
                            avlItemId: avl_mod_123
                            quantity: 25
                          - category: inverter
                            avlItemId: avl_inv_456
                            quantity: 25
                          - category: racking
                            avlItemId: avl_rack_789
                        financials:
                          epcAmount: 32000
                          dcBonusRecipient: customer
                        stateFields:
                          utilityBillsUsed: "Yes"
                          preSolarTariff: E-TOU-C
                          postSolarTariff: E-ELEC
                          estimatedSavingsMaxBill: 1450
                      prefilledFields:
                        - financials.payments[1].name
                        - sales.installStartDate
                        - sales.ptoDate
                        - system.energySavingsCalculator
                      pricing:
                        quoteId: q_5Tn8Wc2Lx9Pr4Kd7
                        netAmountDue: 23680.36
                        leaseAmount: 23680.36
                        replacementCost: 32000
                        basis: epc
                        epcAmount: 32000
                        targetNetAmountDue: null
                      validation:
                        readyToSend: false
                        issues:
                          - step: financials
                            field: financials.payments
                            code: PAYMENTS_DO_NOT_SUM
                            message: The payments add up to $0.00 but the Net Amount Due is $23,680.36. They must match to the cent.
                            severity: error
                      warnings: []
                      portalUrl: https://raceway.participate.energy/projects/new?tab=drafts&draft=cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      projectId: null
                      packetId: null
                      dryRun: false
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, PRODUCT_NOT_ENABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                PRODUCT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_PRODUCT_NOT_ENABLED"
        "409":
          description: "Conflict with the current state. Codes: EXTERNAL_ID_IN_USE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                EXTERNAL_ID_IN_USE:
                  $ref: "#/components/examples/Error_EXTERNAL_ID_IN_USE"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: ASSIGNEE_NOT_FOUND, ASSIGNEE_NOT_PERMITTED, PREFILL_LOCKED_FIELD, EQUIPMENT_NOT_ALLOWED_BY_PREFILL, PRODUCT_NOT_SUPPORTED_BY_API, ADDRESS_PO_BOX, EPC_OUT_OF_RANGE, SYSTEM_SIZE_LOOKS_LIKE_WATTS, SYSTEM_SIZE_OUT_OF_RANGE, SYSTEM_SIZE_MISMATCH, CONTRACT_DATE_OUT_OF_RANGE, EQUIPMENT_NOT_ON_AVL, EQUIPMENT_AMBIGUOUS, EQUIPMENT_WRONG_CATEGORY, INCENTIVE_NOT_AVAILABLE, STATE_NOT_SUPPORTED, ADDRESS_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ASSIGNEE_NOT_FOUND:
                  $ref: "#/components/examples/Error_ASSIGNEE_NOT_FOUND"
                ASSIGNEE_NOT_PERMITTED:
                  $ref: "#/components/examples/Error_ASSIGNEE_NOT_PERMITTED"
                PREFILL_LOCKED_FIELD:
                  $ref: "#/components/examples/Error_PREFILL_LOCKED_FIELD"
                EQUIPMENT_NOT_ALLOWED_BY_PREFILL:
                  $ref: "#/components/examples/Error_EQUIPMENT_NOT_ALLOWED_BY_PREFILL"
                PRODUCT_NOT_SUPPORTED_BY_API:
                  $ref: "#/components/examples/Error_PRODUCT_NOT_SUPPORTED_BY_API"
                ADDRESS_PO_BOX:
                  $ref: "#/components/examples/Error_ADDRESS_PO_BOX"
                EPC_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EPC_OUT_OF_RANGE"
                SYSTEM_SIZE_LOOKS_LIKE_WATTS:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_LOOKS_LIKE_WATTS"
                SYSTEM_SIZE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_OUT_OF_RANGE"
                SYSTEM_SIZE_MISMATCH:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_MISMATCH"
                CONTRACT_DATE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_CONTRACT_DATE_OUT_OF_RANGE"
                EQUIPMENT_NOT_ON_AVL:
                  $ref: "#/components/examples/Error_EQUIPMENT_NOT_ON_AVL"
                EQUIPMENT_AMBIGUOUS:
                  $ref: "#/components/examples/Error_EQUIPMENT_AMBIGUOUS"
                EQUIPMENT_WRONG_CATEGORY:
                  $ref: "#/components/examples/Error_EQUIPMENT_WRONG_CATEGORY"
                INCENTIVE_NOT_AVAILABLE:
                  $ref: "#/components/examples/Error_INCENTIVE_NOT_AVAILABLE"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
                ADDRESS_NOT_FOUND:
                  $ref: "#/components/examples/Error_ADDRESS_NOT_FOUND"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:write
      x-pe-scope: contracts:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /contract-drafts/defaults:
    get:
      operationId: getContractDraftDefaults
      tags:
        - Contract drafts
      summary: Read your prefill for a state
      description: |-
        The defaults a new draft gets in this state from your company's prefill, the locked fields, the excluded equipment (one row per AVL item id), the included incentives of the state, the state's contract fields (`stateFields` keys with their types, `min`, `max`, `zeroAllowed`, `required` and `requiredForSystemTypes`), `stateSpecificFields` (the body fields outside `stateFields` that only this state's contract has) and the state's customer agreement (`contractTemplate`: `available`, `cosignerAllowed` and the `requiredFields` its mandatory fields need, where an entry with `anyOf` is filled by any one of the listed body fields; `null` when PE could not read it, and `available: false` with an `issue` when no contract can be sent in the state).

        **Scope:** `contracts:write`. **X-PE-Actor-Email:** optional.

        **Errors:** only the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: stateCode
          in: query
          required: true
          schema:
            type: string
          description: A 2-letter US state code.
        - name: utility
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 200
          description: "The utility name (the `utility.name` you will send). With it, only the included incentives that apply to that utility are listed, as a draft build filters them. Without it, every included incentive of the state is listed with its requiresUtility, and `utility` and `utilityRecognized` in the response are null. A name PE does not recognize gives utility null and utilityRecognized false. A draft carries the included incentives your prefill names (defaults.includedIncentives) first, and the utility's applicable ones when the prefill names none; a prefill incentive the state does not offer is left out of the draft (warning PREFILL_INCENTIVE_NOT_APPLICABLE) and is not listed in defaults. Send an amount for each; outside New York send 0 (a non-zero included amount is priced only in New York)."
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractDraftDefaultsResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      stateCode: CA
                      utility: null
                      utilityRecognized: null
                      defaults:
                        milestones:
                          - name: null
                            percent: 0
                          - name: Install Complete
                            percent: 100
                        timeline:
                          contractToInstallDays: 45
                          contractToPtoDays: 90
                        lender: null
                        paymentInstructions: null
                        dcBonusRecipient: installer
                        energySavingsCalculator: Aurora
                        additionalProducts: []
                        incentives: []
                        includedIncentives: []
                      includedIncentivesForState: []
                      locks:
                        - field: financials.dcBonusRecipient
                          value: installer
                      equipmentLimits:
                        - category: pv_module
                          excluded:
                            - name: Example Solar - EX400
                              avlItemId: avl_mod_999
                      stateFields:
                        - key: utilityBillsUsed
                          label: Production Sizing Method
                          type: select
                          required: true
                          options:
                            - "Yes"
                            - "No"
                          requiredForSystemTypes: null
                          min: null
                          max: null
                          zeroAllowed: null
                          source: built_in
                      stateSpecificFields: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:write
      x-pe-scope: contracts:write
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /contract-drafts/{draftId}:
    get:
      operationId: getContractDraft
      tags:
        - Contract drafts
      summary: Read a contract draft
      description: |-
        One draft. `validation` is the result of the last API create or update; use the validate call to check the values the draft holds now.

        **Scope:** `contracts:write`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`DRAFT_NOT_FOUND`](#error-DRAFT_NOT_FOUND).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: draftId
          in: path
          required: true
          description: The draft id (cdr_...).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractDraftResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      draftId: cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      status: draft
                      assignedTo:
                        email: riley@acme-solar.example
                        name: Riley Rep
                      externalId: crm-10442
                      label: Jordan Example (Sacramento, CA)
                      stateCode: CA
                      productType: Synthetic Cash
                      createdAt: "2026-11-12T18:02:11.482Z"
                      updatedAt: "2026-11-12T18:02:11.482Z"
                      body:
                        externalId: crm-10442
                        customer:
                          firstName: Jordan
                          lastName: Example
                          email: jordan@example.com
                          phone: 555-010-0199
                        siteAddress:
                          street: 100 Example Street
                          city: Sacramento
                          stateCode: CA
                          zipCode: "95814"
                        utility:
                          name: Pacific Gas & Electric
                        system:
                          systemType: Solar Only
                          annualUsageKwh: 10500
                          annualProductionKwh: 12000
                        equipment:
                          - category: module
                            avlItemId: avl_mod_123
                            quantity: 25
                          - category: inverter
                            avlItemId: avl_inv_456
                            quantity: 25
                          - category: racking
                            avlItemId: avl_rack_789
                        financials:
                          epcAmount: 32000
                          dcBonusRecipient: customer
                        stateFields:
                          utilityBillsUsed: "Yes"
                          preSolarTariff: E-TOU-C
                          postSolarTariff: E-ELEC
                          estimatedSavingsMaxBill: 1450
                      prefilledFields:
                        - financials.payments[1].name
                        - sales.installStartDate
                        - sales.ptoDate
                        - system.energySavingsCalculator
                      pricing:
                        quoteId: q_5Tn8Wc2Lx9Pr4Kd7
                        netAmountDue: 23680.36
                        leaseAmount: 23680.36
                        replacementCost: 32000
                        basis: epc
                        epcAmount: 32000
                        targetNetAmountDue: null
                      validation:
                        readyToSend: false
                        issues:
                          - step: financials
                            field: financials.payments
                            code: PAYMENTS_DO_NOT_SUM
                            message: The payments add up to $0.00 but the Net Amount Due is $23,680.36. They must match to the cent.
                            severity: error
                      warnings: []
                      portalUrl: https://raceway.participate.energy/projects/new?tab=drafts&draft=cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      projectId: null
                      packetId: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: DRAFT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_NOT_FOUND:
                  $ref: "#/components/examples/Error_DRAFT_NOT_FOUND"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:write
      x-pe-scope: contracts:write
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
    patch:
      operationId: updateContractDraft
      tags:
        - Contract drafts
      summary: Update a contract draft
      description: |-
        Merge a change into the draft: objects merge, lists replace, `null` clears. PE builds the draft again from the merged body and your prefill, prices it again and validates it. Edits the rep made in the portal are replaced. Refused once the draft is being sent or was sent.

        **Scope:** `contracts:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`DRAFT_NOT_FOUND`](#error-DRAFT_NOT_FOUND), [`DRAFT_ALREADY_SENT`](#error-DRAFT_ALREADY_SENT), [`DRAFT_SEND_IN_PROGRESS`](#error-DRAFT_SEND_IN_PROGRESS), [`ASSIGNEE_NOT_FOUND`](#error-ASSIGNEE_NOT_FOUND), [`ASSIGNEE_NOT_PERMITTED`](#error-ASSIGNEE_NOT_PERMITTED), [`PREFILL_LOCKED_FIELD`](#error-PREFILL_LOCKED_FIELD), [`EQUIPMENT_NOT_ALLOWED_BY_PREFILL`](#error-EQUIPMENT_NOT_ALLOWED_BY_PREFILL), [`PRODUCT_NOT_SUPPORTED_BY_API`](#error-PRODUCT_NOT_SUPPORTED_BY_API), [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX), [`EPC_OUT_OF_RANGE`](#error-EPC_OUT_OF_RANGE), [`SYSTEM_SIZE_LOOKS_LIKE_WATTS`](#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS), [`SYSTEM_SIZE_OUT_OF_RANGE`](#error-SYSTEM_SIZE_OUT_OF_RANGE), [`SYSTEM_SIZE_MISMATCH`](#error-SYSTEM_SIZE_MISMATCH), [`CONTRACT_DATE_OUT_OF_RANGE`](#error-CONTRACT_DATE_OUT_OF_RANGE), [`CONTRACT_DATE_BEFORE_RETITC_CUTOFF`](#error-CONTRACT_DATE_BEFORE_RETITC_CUTOFF), [`EQUIPMENT_NOT_ON_AVL`](#error-EQUIPMENT_NOT_ON_AVL), [`EQUIPMENT_AMBIGUOUS`](#error-EQUIPMENT_AMBIGUOUS), [`EQUIPMENT_WRONG_CATEGORY`](#error-EQUIPMENT_WRONG_CATEGORY), [`INCENTIVE_NOT_AVAILABLE`](#error-INCENTIVE_NOT_AVAILABLE), [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED), [`ADDRESS_NOT_FOUND`](#error-ADDRESS_NOT_FOUND), [`PRODUCT_NOT_ENABLED`](#error-PRODUCT_NOT_ENABLED), [`EXTERNAL_ID_IN_USE`](#error-EXTERNAL_ID_IN_USE).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: draftId
          in: path
          required: true
          description: The draft id (cdr_...).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractDraftPatchRequest"
            examples:
              example:
                summary: Example
                value:
                  financials:
                    payments:
                      - amount: 500
                      - name: Install Complete
                        amount: 23180.36
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractDraftResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      draftId: cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      status: draft
                      assignedTo:
                        email: riley@acme-solar.example
                        name: Riley Rep
                      externalId: crm-10442
                      label: Jordan Example (Sacramento, CA)
                      stateCode: CA
                      productType: Synthetic Cash
                      createdAt: "2026-11-12T18:02:11.482Z"
                      updatedAt: "2026-11-12T18:02:11.482Z"
                      body:
                        externalId: crm-10442
                        customer:
                          firstName: Jordan
                          lastName: Example
                          email: jordan@example.com
                          phone: 555-010-0199
                        siteAddress:
                          street: 100 Example Street
                          city: Sacramento
                          stateCode: CA
                          zipCode: "95814"
                        utility:
                          name: Pacific Gas & Electric
                        system:
                          systemType: Solar Only
                          annualUsageKwh: 10500
                          annualProductionKwh: 12000
                        equipment:
                          - category: module
                            avlItemId: avl_mod_123
                            quantity: 25
                          - category: inverter
                            avlItemId: avl_inv_456
                            quantity: 25
                          - category: racking
                            avlItemId: avl_rack_789
                        financials:
                          epcAmount: 32000
                          dcBonusRecipient: customer
                        stateFields:
                          utilityBillsUsed: "Yes"
                          preSolarTariff: E-TOU-C
                          postSolarTariff: E-ELEC
                          estimatedSavingsMaxBill: 1450
                      prefilledFields:
                        - financials.payments[1].name
                        - sales.installStartDate
                        - sales.ptoDate
                        - system.energySavingsCalculator
                      pricing:
                        quoteId: q_5Tn8Wc2Lx9Pr4Kd7
                        netAmountDue: 23680.36
                        leaseAmount: 23680.36
                        replacementCost: 32000
                        basis: epc
                        epcAmount: 32000
                        targetNetAmountDue: null
                      validation:
                        readyToSend: true
                        issues: []
                      warnings: []
                      portalUrl: https://raceway.participate.energy/projects/new?tab=drafts&draft=cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      projectId: null
                      packetId: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, PRODUCT_NOT_ENABLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                PRODUCT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_PRODUCT_NOT_ENABLED"
        "404":
          description: "Not found. Codes: DRAFT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_NOT_FOUND:
                  $ref: "#/components/examples/Error_DRAFT_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: DRAFT_ALREADY_SENT, DRAFT_SEND_IN_PROGRESS, EXTERNAL_ID_IN_USE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_ALREADY_SENT:
                  $ref: "#/components/examples/Error_DRAFT_ALREADY_SENT"
                DRAFT_SEND_IN_PROGRESS:
                  $ref: "#/components/examples/Error_DRAFT_SEND_IN_PROGRESS"
                EXTERNAL_ID_IN_USE:
                  $ref: "#/components/examples/Error_EXTERNAL_ID_IN_USE"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: ASSIGNEE_NOT_FOUND, ASSIGNEE_NOT_PERMITTED, PREFILL_LOCKED_FIELD, EQUIPMENT_NOT_ALLOWED_BY_PREFILL, PRODUCT_NOT_SUPPORTED_BY_API, ADDRESS_PO_BOX, EPC_OUT_OF_RANGE, SYSTEM_SIZE_LOOKS_LIKE_WATTS, SYSTEM_SIZE_OUT_OF_RANGE, SYSTEM_SIZE_MISMATCH, CONTRACT_DATE_OUT_OF_RANGE, EQUIPMENT_NOT_ON_AVL, EQUIPMENT_AMBIGUOUS, EQUIPMENT_WRONG_CATEGORY, INCENTIVE_NOT_AVAILABLE, STATE_NOT_SUPPORTED, ADDRESS_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ASSIGNEE_NOT_FOUND:
                  $ref: "#/components/examples/Error_ASSIGNEE_NOT_FOUND"
                ASSIGNEE_NOT_PERMITTED:
                  $ref: "#/components/examples/Error_ASSIGNEE_NOT_PERMITTED"
                PREFILL_LOCKED_FIELD:
                  $ref: "#/components/examples/Error_PREFILL_LOCKED_FIELD"
                EQUIPMENT_NOT_ALLOWED_BY_PREFILL:
                  $ref: "#/components/examples/Error_EQUIPMENT_NOT_ALLOWED_BY_PREFILL"
                PRODUCT_NOT_SUPPORTED_BY_API:
                  $ref: "#/components/examples/Error_PRODUCT_NOT_SUPPORTED_BY_API"
                ADDRESS_PO_BOX:
                  $ref: "#/components/examples/Error_ADDRESS_PO_BOX"
                EPC_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EPC_OUT_OF_RANGE"
                SYSTEM_SIZE_LOOKS_LIKE_WATTS:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_LOOKS_LIKE_WATTS"
                SYSTEM_SIZE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_OUT_OF_RANGE"
                SYSTEM_SIZE_MISMATCH:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_MISMATCH"
                CONTRACT_DATE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_CONTRACT_DATE_OUT_OF_RANGE"
                EQUIPMENT_NOT_ON_AVL:
                  $ref: "#/components/examples/Error_EQUIPMENT_NOT_ON_AVL"
                EQUIPMENT_AMBIGUOUS:
                  $ref: "#/components/examples/Error_EQUIPMENT_AMBIGUOUS"
                EQUIPMENT_WRONG_CATEGORY:
                  $ref: "#/components/examples/Error_EQUIPMENT_WRONG_CATEGORY"
                INCENTIVE_NOT_AVAILABLE:
                  $ref: "#/components/examples/Error_INCENTIVE_NOT_AVAILABLE"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
                ADDRESS_NOT_FOUND:
                  $ref: "#/components/examples/Error_ADDRESS_NOT_FOUND"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:write
      x-pe-scope: contracts:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
    delete:
      operationId: deleteContractDraft
      tags:
        - Contract drafts
      summary: Delete a contract draft
      description: |-
        Delete the draft. Refused once it is being sent or was sent.

        **Scope:** `contracts:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`DRAFT_NOT_FOUND`](#error-DRAFT_NOT_FOUND), [`DRAFT_ALREADY_SENT`](#error-DRAFT_ALREADY_SENT), [`DRAFT_SEND_IN_PROGRESS`](#error-DRAFT_SEND_IN_PROGRESS).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: draftId
          in: path
          required: true
          description: The draft id (cdr_...).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractDraftDeleteResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      draftId: cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      deleted: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                VALIDATION_FAILED:
                  $ref: "#/components/examples/Error_VALIDATION_FAILED"
                UNKNOWN_FIELD:
                  $ref: "#/components/examples/Error_UNKNOWN_FIELD"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: DRAFT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_NOT_FOUND:
                  $ref: "#/components/examples/Error_DRAFT_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: DRAFT_ALREADY_SENT, DRAFT_SEND_IN_PROGRESS."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_ALREADY_SENT:
                  $ref: "#/components/examples/Error_DRAFT_ALREADY_SENT"
                DRAFT_SEND_IN_PROGRESS:
                  $ref: "#/components/examples/Error_DRAFT_SEND_IN_PROGRESS"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:write
      x-pe-scope: contracts:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /contract-drafts/{draftId}/validate:
    post:
      operationId: validateContractDraft
      tags:
        - Contract drafts
      summary: Validate a contract draft
      description: |-
        Run the Contract Builder's checks and the send's agreement checks on the values the draft holds now, including edits the rep made in the portal. Nothing is written and the price is not calculated again (`PRICING_STALE` tells you a pricing input changed). Send no body or an empty object.

        **Scope:** `contracts:write`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`DRAFT_NOT_FOUND`](#error-DRAFT_NOT_FOUND).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: draftId
          in: path
          required: true
          description: The draft id (cdr_...).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractDraftValidateResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      draftId: cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      status: draft
                      validation:
                        readyToSend: true
                        issues: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: DRAFT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_NOT_FOUND:
                  $ref: "#/components/examples/Error_DRAFT_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:write
      x-pe-scope: contracts:write
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /contract-drafts/{draftId}/send:
    post:
      operationId: sendContractDraft
      tags:
        - Contract drafts
      summary: Send a contract draft for e-signature
      description: |-
        Send a draft for e-signature: PE checks the draft, creates the project and emails the contract to the homeowner, the same outcome as Send in the portal. The rep who owns the draft is the sender and must be an administrator or editor. Send no body or an empty object. A repeated send of a sent draft returns the stored answer with HTTP 200, with the contract's current `status` and signers; a draft the rep sent from the portal answers with its `projectId` and `packetId` null. When the project was created but the send failed, the error names the `projectId` and the draft is `sent_create_only`; send again. Test keys create a Test project and a simulated contract and email nobody. See Contract drafts and e-sign.

        **Scope:** `contracts:send`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`DRAFT_NOT_FOUND`](#error-DRAFT_NOT_FOUND), [`DRAFT_SEND_IN_PROGRESS`](#error-DRAFT_SEND_IN_PROGRESS), [`DRAFT_PORTAL_SEND_UNCONFIRMED`](#error-DRAFT_PORTAL_SEND_UNCONFIRMED), [`DRAFT_STATE_INVALID`](#error-DRAFT_STATE_INVALID), [`DRAFT_NOT_READY`](#error-DRAFT_NOT_READY), [`ASSIGNEE_NOT_FOUND`](#error-ASSIGNEE_NOT_FOUND), [`ASSIGNEE_NOT_PERMITTED`](#error-ASSIGNEE_NOT_PERMITTED), [`INSTALLER_ON_HOLD`](#error-INSTALLER_ON_HOLD), [`STATE_NOT_SUPPORTED`](#error-STATE_NOT_SUPPORTED), [`STATE_NOT_ACTIVE_FOR_INSTALLER`](#error-STATE_NOT_ACTIVE_FOR_INSTALLER), [`EXTERNAL_ID_IN_USE`](#error-EXTERNAL_ID_IN_USE), [`CONTRACT_TEMPLATE_NOT_FOUND`](#error-CONTRACT_TEMPLATE_NOT_FOUND), [`AUTO_SIGNER_REQUIRED`](#error-AUTO_SIGNER_REQUIRED), [`CONTRACT_NOT_SENDABLE`](#error-CONTRACT_NOT_SENDABLE), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`CONTRACT_SEND_FAILED`](#error-CONTRACT_SEND_FAILED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: draftId
          in: path
          required: true
          description: The draft id (cdr_...).
          schema:
            type: string
      responses:
        "200":
          description: "A repeated send of a sent draft: the stored answer. Nothing is sent."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractSendResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-EXAM1
                      packetId: pkt4Hn8Qa2Zt6WcYb1Lm
                      draftId: cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      status: sent
                      installerSignMethod: auto_applied
                      installerSigningUrl: null
                      signers:
                        - role: customer
                          name: Jordan Example
                          email: jordan@example.com
                          status: sent
                        - role: installer
                          name: Morgan Owner
                          email: morgan@acme-solar.example
                          status: signed
                        - role: pe
                          name: Participate Energy
                          email: null
                          status: pending
                      testMode: false
                      warnings: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18:02:11.482Z"
        "201":
          description: "Sent: the project exists and the contract is out for signature."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractSendResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-EXAM1
                      packetId: pkt4Hn8Qa2Zt6WcYb1Lm
                      draftId: cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K
                      status: sent
                      installerSignMethod: auto_applied
                      installerSigningUrl: null
                      signers:
                        - role: customer
                          name: Jordan Example
                          email: jordan@example.com
                          status: sent
                        - role: installer
                          name: Morgan Owner
                          email: morgan@acme-solar.example
                          status: signed
                        - role: pe
                          name: Participate Energy
                          email: null
                          status: pending
                      testMode: false
                      warnings: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, INSTALLER_ON_HOLD, STATE_NOT_ACTIVE_FOR_INSTALLER."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                INSTALLER_ON_HOLD:
                  $ref: "#/components/examples/Error_INSTALLER_ON_HOLD"
                STATE_NOT_ACTIVE_FOR_INSTALLER:
                  $ref: "#/components/examples/Error_STATE_NOT_ACTIVE_FOR_INSTALLER"
        "404":
          description: "Not found. Codes: DRAFT_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_NOT_FOUND:
                  $ref: "#/components/examples/Error_DRAFT_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: DRAFT_SEND_IN_PROGRESS, EXTERNAL_ID_IN_USE, PROJECT_CANCELLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_SEND_IN_PROGRESS:
                  $ref: "#/components/examples/Error_DRAFT_SEND_IN_PROGRESS"
                DRAFT_PORTAL_SEND_UNCONFIRMED:
                  $ref: "#/components/examples/Error_DRAFT_PORTAL_SEND_UNCONFIRMED"
                DRAFT_STATE_INVALID:
                  $ref: "#/components/examples/Error_DRAFT_STATE_INVALID"
                EXTERNAL_ID_IN_USE:
                  $ref: "#/components/examples/Error_EXTERNAL_ID_IN_USE"
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: DRAFT_NOT_READY, ASSIGNEE_NOT_FOUND, ASSIGNEE_NOT_PERMITTED, STATE_NOT_SUPPORTED, CONTRACT_TEMPLATE_NOT_FOUND, AUTO_SIGNER_REQUIRED, CONTRACT_NOT_SENDABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DRAFT_NOT_READY:
                  $ref: "#/components/examples/Error_DRAFT_NOT_READY"
                ASSIGNEE_NOT_FOUND:
                  $ref: "#/components/examples/Error_ASSIGNEE_NOT_FOUND"
                ASSIGNEE_NOT_PERMITTED:
                  $ref: "#/components/examples/Error_ASSIGNEE_NOT_PERMITTED"
                STATE_NOT_SUPPORTED:
                  $ref: "#/components/examples/Error_STATE_NOT_SUPPORTED"
                CONTRACT_TEMPLATE_NOT_FOUND:
                  $ref: "#/components/examples/Error_CONTRACT_TEMPLATE_NOT_FOUND"
                AUTO_SIGNER_REQUIRED:
                  $ref: "#/components/examples/Error_AUTO_SIGNER_REQUIRED"
                CONTRACT_NOT_SENDABLE:
                  $ref: "#/components/examples/Error_CONTRACT_NOT_SENDABLE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          description: "The e-sign send failed after the project was created. Codes: CONTRACT_SEND_FAILED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                CONTRACT_SEND_FAILED:
                  $ref: "#/components/examples/Error_CONTRACT_SEND_FAILED"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:send
      x-pe-scope: contracts:send
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/contract-esign:
    get:
      operationId: getContractEsign
      tags:
        - Contract e-sign
      summary: Read the project's contract
      description: |-
        The project's current contract: its newest contract sent for e-signature that is not cancelled, from the API or the portal, with its status and signers. Test keys also get `documents`: download links to the rendered contract PDF that work for 15 minutes.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PACKET_NOT_FOUND`](#error-PACKET_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractEsignResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-EXAM1
                      packetId: pkt4Hn8Qa2Zt6WcYb1Lm
                      status: partially_signed
                      templateName: California Customer Agreement
                      installerSignMethod: auto_applied
                      sentAt: "2026-11-12T18:02:12.000Z"
                      completedAt: null
                      expiresAt: "2026-12-12T18:02:12.000Z"
                      voidedReason: null
                      declineReason: null
                      signers:
                        - role: customer
                          name: Jordan Example
                          email: jordan@example.com
                          status: signed
                          signedAt: "2026-11-12T19:01:44.000Z"
                          viewed: true
                        - role: cosigner
                          name: Casey Example
                          email: casey@example.com
                          status: viewed
                          signedAt: null
                          viewed: true
                        - role: installer
                          name: Morgan Owner
                          email: morgan@acme-solar.example
                          status: signed
                          signedAt: "2026-11-12T18:02:12.000Z"
                          viewed: true
                      testMode: false
                      documentsRendered: null
                      documentsNotRenderedReason: null
                      documents: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND, PACKET_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
                PACKET_NOT_FOUND:
                  $ref: "#/components/examples/Error_PACKET_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/{projectId}/contract-esign/send:
    post:
      operationId: resendContractEsign
      tags:
        - Contract e-sign
      summary: Send the project's contract again
      description: |-
        Send the project's contract again, built from the project as it is now. PE voids the contract that is out for signature first, as the portal does. A signed (completed) contract is not sent again (`CONTRACT_ALREADY_SIGNED`). The sender is the user in `assignedToEmail`, else the `X-PE-Actor-Email` user, and must be an administrator or editor. Test keys create a new simulated contract and email nobody.

        **Scope:** `contracts:send`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`CONTRACT_ALREADY_SIGNED`](#error-CONTRACT_ALREADY_SIGNED), [`ASSIGNEE_NOT_FOUND`](#error-ASSIGNEE_NOT_FOUND), [`ASSIGNEE_NOT_PERMITTED`](#error-ASSIGNEE_NOT_PERMITTED), [`CONTRACT_TEMPLATE_NOT_FOUND`](#error-CONTRACT_TEMPLATE_NOT_FOUND), [`AUTO_SIGNER_REQUIRED`](#error-AUTO_SIGNER_REQUIRED), [`CONTRACT_NOT_SENDABLE`](#error-CONTRACT_NOT_SENDABLE), [`CONTRACT_SEND_FAILED`](#error-CONTRACT_SEND_FAILED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractResendRequest"
            examples:
              example:
                summary: Example
                value:
                  assignedToEmail: riley@acme-solar.example
      responses:
        "201":
          description: Sent.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractSendResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-EXAM1
                      packetId: pkt9Rt3Lm5Xc8VbQ2Wn7
                      draftId: null
                      status: sent
                      installerSignMethod: auto_applied
                      installerSigningUrl: null
                      signers:
                        - role: customer
                          name: Jordan Example
                          email: jordan@example.com
                          status: sent
                        - role: installer
                          name: Morgan Owner
                          email: morgan@acme-solar.example
                          status: signed
                        - role: pe
                          name: Participate Energy
                          email: null
                          status: pending
                      testMode: false
                      warnings: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, CONTRACT_ALREADY_SIGNED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                CONTRACT_ALREADY_SIGNED:
                  $ref: "#/components/examples/Error_CONTRACT_ALREADY_SIGNED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: ASSIGNEE_NOT_FOUND, ASSIGNEE_NOT_PERMITTED, CONTRACT_TEMPLATE_NOT_FOUND, AUTO_SIGNER_REQUIRED, CONTRACT_NOT_SENDABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ASSIGNEE_NOT_FOUND:
                  $ref: "#/components/examples/Error_ASSIGNEE_NOT_FOUND"
                ASSIGNEE_NOT_PERMITTED:
                  $ref: "#/components/examples/Error_ASSIGNEE_NOT_PERMITTED"
                CONTRACT_TEMPLATE_NOT_FOUND:
                  $ref: "#/components/examples/Error_CONTRACT_TEMPLATE_NOT_FOUND"
                AUTO_SIGNER_REQUIRED:
                  $ref: "#/components/examples/Error_AUTO_SIGNER_REQUIRED"
                CONTRACT_NOT_SENDABLE:
                  $ref: "#/components/examples/Error_CONTRACT_NOT_SENDABLE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          description: "The e-sign send failed after the project was created. Codes: CONTRACT_SEND_FAILED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                CONTRACT_SEND_FAILED:
                  $ref: "#/components/examples/Error_CONTRACT_SEND_FAILED"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:send
      x-pe-scope: contracts:send
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/contract-esign/void:
    post:
      operationId: voidContractEsign
      tags:
        - Contract e-sign
      summary: Void the project's contract
      description: |-
        Void the project's current contract. The signers can no longer sign it. `reason` (1 to 500 characters) is recorded. A completed or voided contract cannot be voided.

        **Scope:** `contracts:send`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PACKET_NOT_FOUND`](#error-PACKET_NOT_FOUND), [`PACKET_NOT_VOIDABLE`](#error-PACKET_NOT_VOIDABLE).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractVoidRequest"
            examples:
              example:
                summary: Example
                value:
                  reason: The system size changed.
      responses:
        "200":
          description: Voided.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractVoidResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-EXAM1
                      packetId: pkt4Hn8Qa2Zt6WcYb1Lm
                      status: voided
                      previousStatus: sent
                      voidedReason: The system size changed.
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-12T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND, PACKET_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
                PACKET_NOT_FOUND:
                  $ref: "#/components/examples/Error_PACKET_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PACKET_NOT_VOIDABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PACKET_NOT_VOIDABLE:
                  $ref: "#/components/examples/Error_PACKET_NOT_VOIDABLE"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - contracts:send
      x-pe-scope: contracts:send
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects:
    get:
      operationId: listProjects
      tags:
        - Projects
      summary: List your projects
      description: |-
        List your projects, newest change first. Filter by `externalId`, `status`, `milestone` and `updatedSince`. Page with `limit` and `cursor`. To sync, call it with `updatedSince` set to the latest `updatedAt` you saw.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`CURSOR_INVALID`](#error-CURSOR_INVALID).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: externalId
          in: query
          required: false
          description: Only the project with this external ID.
          schema:
            type: string
            minLength: 1
            maxLength: 64
        - name: status
          in: query
          required: false
          description: Only projects with this status.
          schema:
            type: string
            enum:
              - Active
              - At-risk
              - Not Submitted
              - Pending Cancellation
              - DQ
              - Cancelled
              - Cancelled-Duplicate
              - Completed
              - On Hold
        - name: milestone
          in: query
          required: false
          description: Only projects at this milestone.
          schema:
            type: string
            enum:
              - Project Onboarded
              - Inspection Complete
              - Project Complete
              - Closed
              - Cancellation In Progress
        - name: updatedSince
          in: query
          required: false
          description: YYYY-MM-DD or an ISO 8601 timestamp with an offset.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1 to 100. Default 25.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          required: false
          description: The nextCursor of the previous page. Send the same filters.
          schema:
            type: string
            maxLength: 256
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projects:
                        - projectId: CA2611-SMIT1
                          externalId: crm-10442
                          status: Active
                          deleted: false
                          milestone: Project Onboarded
                          documentReviewStatus: Action Required (Installer)
                          customer:
                            firstName: Jordan
                            lastName: Example
                          site:
                            city: Sacramento
                            state: California
                            stateCode: CA
                          approvals:
                            ic:
                              status: not_started
                              date: null
                            pc:
                              status: not_started
                              date: null
                          actions:
                            open: 1
                          updatedAt: "2026-11-10T21:14:55.000Z"
                      nextCursor: eyJmIjoiLi4uIn0
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, VALIDATION_FAILED, UNKNOWN_FIELD, CURSOR_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                CURSOR_INVALID:
                  $ref: "#/components/examples/Error_CURSOR_INVALID"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/by-external-id/{externalId}:
    get:
      operationId: getProjectByExternalId
      tags:
        - Projects
      summary: Read a project by external ID
      description: |-
        Read a project by your own id. The response is the same as `GET /projects/{projectId}`.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`EXTERNAL_ID_AMBIGUOUS`](#error-EXTERNAL_ID_AMBIGUOUS).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
        - name: externalId
          in: path
          required: true
          description: Your external ID of the project.
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDetailResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      externalId: crm-10442
                      status: Active
                      deleted: false
                      milestone: Project Onboarded
                      documentReviewStatus: Action Required (Installer)
                      productType: Synthetic Cash
                      contractType: installer_originated
                      source:
                        channel: INSTALLER_API
                        grantId: igr_4bT9xQ2mK7pL1sV8nR3c
                      createdAt: "2026-11-02T17:20:04.000Z"
                      updatedAt: "2026-11-10T21:14:55.000Z"
                      customer:
                        firstName: Jordan
                        lastName: Example
                        email: jordan@example.com
                        phone: 555-010-0199
                        mailingSameAsSite: true
                      site:
                        street: 100 Example Street
                        city: Sacramento
                        state: California
                        stateCode: CA
                        zipCode: "95814"
                      utility:
                        name: Pacific Gas and Electric
                      existingSolarOnProperty: false
                      installer:
                        externalId: crm-10442
                        salesRepName: Riley Rep
                        salesRepEmail: riley@installer.example
                        submittedByEmail: riley@installer.example
                      dates:
                        onboarded: "2026-11-02"
                        contractSigned: "2026-10-30"
                        icApproval: null
                        icPayment: null
                        pto: null
                        pcApproval: null
                        pcPayment: null
                        forecastedInstall: "2026-12-04"
                        forecastedPto: null
                      approvals:
                        ic:
                          status: not_started
                          date: null
                        pc:
                          status: not_started
                          date: null
                      financials:
                        epcAmount: 30000
                        eligibleRoofingCost: 0
                        adjustedEpcAmount: 30000
                        ineligibleRoofingCost: 0
                        replacementCost: 30000
                        leaseFactor: 1.4285714
                        discountedAmount: 21000
                        baselineLeaseAmount: 21000
                        stateIncentive: null
                        utilityIncentive: null
                        netAmountDue: 21000
                        pePayout: 9000
                        icPayment: 6000
                        pcPayment: 3000
                        dcBonusRecipient: Installer
                        lender: null
                        amountFinanced: null
                        insuranceOption: "1"
                        insuranceRiskAdjustment: 0
                        salesTaxRate: 0
                        salesTaxAmount: 0
                      safeHarbor:
                        opportunityId: null
                      system:
                        type: Solar Only
                        sizeKw: 8.6
                        storageKwh: null
                        equipment:
                          - category: module
                            avlItemId: avl_8Hc2Kd91LmQ4
                            name: Qcells - Q.TRON BLK M-G2+ 430
                            manufacturer: Qcells
                            model: Q.TRON BLK M-G2+ 430
                            quantity: 20
                          - category: inverter
                            avlItemId: avl_3Pq7Rt55XyZ2
                            name: Enphase - IQ8M-72-2-US
                            manufacturer: Enphase
                            model: IQ8M-72-2-US
                            quantity: 20
                      documents:
                        required: 13
                        uploaded: 3
                        approved: 1
                        actionRequired: 1
                      photos:
                        sectionsRequired: 8
                        sectionsMissing:
                          - pv_array_wide
                          - racking
                        reviewStatus: null
                      actions:
                        open: 1
                        total: 2
                      editability:
                        fieldsLocked: false
                        reason: null
                        changeOrderRequiredAfterIc: false
                        externalIdEditable: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: EXTERNAL_ID_AMBIGUOUS."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                EXTERNAL_ID_AMBIGUOUS:
                  $ref: "#/components/examples/Error_EXTERNAL_ID_AMBIGUOUS"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/{projectId}:
    get:
      operationId: getProject
      tags:
        - Projects
      summary: Read a project
      description: |-
        Read a project: customer, site, utility, dates, approvals, the pricing chain, the system and its equipment, document and photo counts, open Actions and the edit state. A cancelled project stays readable with `deleted: true`.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDetailResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      externalId: crm-10442
                      status: Active
                      deleted: false
                      milestone: Project Onboarded
                      documentReviewStatus: Action Required (Installer)
                      productType: Synthetic Cash
                      contractType: installer_originated
                      source:
                        channel: INSTALLER_API
                        grantId: igr_4bT9xQ2mK7pL1sV8nR3c
                      createdAt: "2026-11-02T17:20:04.000Z"
                      updatedAt: "2026-11-10T21:14:55.000Z"
                      customer:
                        firstName: Jordan
                        lastName: Example
                        email: jordan@example.com
                        phone: 555-010-0199
                        mailingSameAsSite: true
                      site:
                        street: 100 Example Street
                        city: Sacramento
                        state: California
                        stateCode: CA
                        zipCode: "95814"
                      utility:
                        name: Pacific Gas and Electric
                      existingSolarOnProperty: false
                      installer:
                        externalId: crm-10442
                        salesRepName: Riley Rep
                        salesRepEmail: riley@installer.example
                        submittedByEmail: riley@installer.example
                      dates:
                        onboarded: "2026-11-02"
                        contractSigned: "2026-10-30"
                        icApproval: null
                        icPayment: null
                        pto: null
                        pcApproval: null
                        pcPayment: null
                        forecastedInstall: "2026-12-04"
                        forecastedPto: null
                      approvals:
                        ic:
                          status: not_started
                          date: null
                        pc:
                          status: not_started
                          date: null
                      financials:
                        epcAmount: 30000
                        eligibleRoofingCost: 0
                        adjustedEpcAmount: 30000
                        ineligibleRoofingCost: 0
                        replacementCost: 30000
                        leaseFactor: 1.4285714
                        discountedAmount: 21000
                        baselineLeaseAmount: 21000
                        stateIncentive: null
                        utilityIncentive: null
                        netAmountDue: 21000
                        pePayout: 9000
                        icPayment: 6000
                        pcPayment: 3000
                        dcBonusRecipient: Installer
                        lender: null
                        amountFinanced: null
                        insuranceOption: "1"
                        insuranceRiskAdjustment: 0
                        salesTaxRate: 0
                        salesTaxAmount: 0
                      safeHarbor:
                        opportunityId: null
                      system:
                        type: Solar Only
                        sizeKw: 8.6
                        storageKwh: null
                        equipment:
                          - category: module
                            avlItemId: avl_8Hc2Kd91LmQ4
                            name: Qcells - Q.TRON BLK M-G2+ 430
                            manufacturer: Qcells
                            model: Q.TRON BLK M-G2+ 430
                            quantity: 20
                          - category: inverter
                            avlItemId: avl_3Pq7Rt55XyZ2
                            name: Enphase - IQ8M-72-2-US
                            manufacturer: Enphase
                            model: IQ8M-72-2-US
                            quantity: 20
                      documents:
                        required: 13
                        uploaded: 3
                        approved: 1
                        actionRequired: 1
                      photos:
                        sectionsRequired: 8
                        sectionsMissing:
                          - pv_array_wide
                          - racking
                        reviewStatus: null
                      actions:
                        open: 1
                        total: 2
                      editability:
                        fieldsLocked: false
                        reason: null
                        changeOrderRequiredAfterIc: false
                        externalIdEditable: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
    patch:
      operationId: updateProject
      tags:
        - Projects
      summary: Update project fields
      description: |-
        Change the fields you can edit in the Installer Portal: customer, cosigner, mailing address, utility, sales rep and external ID. Send only the fields you change. See Editing rules. The PTO date is read-only: it comes from the PTO letter (`FIELD_NOT_EDITABLE`). So are `productType`, `contractType`, `site` (they come from the signed contract), `systemType` (a change needs a change order) and `status` (PE sets it): sending one returns `FIELD_NOT_EDITABLE` with the reason.

        The response has `changedFields`, `resignRequired` (the customer must sign again) and `changeOrder` (change order Actions that PE created). Use `?dryRun=true` to check a change first.

        **Scope:** `projects:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`FIELD_NOT_EDITABLE`](#error-FIELD_NOT_EDITABLE), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`PROJECT_LOCKED`](#error-PROJECT_LOCKED), [`PROJECT_CHANGED_SINCE_READ`](#error-PROJECT_CHANGED_SINCE_READ), [`CHANGE_ORDER_BLOCKED`](#error-CHANGE_ORDER_BLOCKED), [`EXTERNAL_ID_TAKEN`](#error-EXTERNAL_ID_TAKEN), [`UTILITY_NOT_RECOGNIZED`](#error-UTILITY_NOT_RECOGNIZED), [`PROJECT_UPDATE_REJECTED`](#error-PROJECT_UPDATE_REJECTED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: dryRun
          in: query
          required: false
          description: "true: check the change and return the result without a write."
          schema:
            type: string
            enum:
              - "true"
              - "false"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectPatchRequest"
            examples:
              example:
                summary: Example
                value:
                  expectedUpdatedAt: "2026-11-10T21:14:55.000Z"
                  customer:
                    phone: 555-010-0123
                  utility:
                    meterId: "1009988776"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectUpdateResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      dryRun: false
                      changed: true
                      changedFields:
                        - customer.phone
                        - utility.meterId
                      resignRequired: false
                      changeOrder:
                        required: false
                        actionIds: []
                      project:
                        projectId: CA2611-SMIT1
                        externalId: crm-10442
                        status: Active
                        deleted: false
                        milestone: Project Onboarded
                        documentReviewStatus: Action Required (Installer)
                        productType: Synthetic Cash
                        contractType: installer_originated
                        source:
                          channel: INSTALLER_API
                          grantId: igr_4bT9xQ2mK7pL1sV8nR3c
                        createdAt: "2026-11-02T17:20:04.000Z"
                        updatedAt: "2026-11-10T21:14:55.000Z"
                        customer:
                          firstName: Jordan
                          lastName: Example
                          email: jordan@example.com
                          phone: 555-010-0199
                          mailingSameAsSite: true
                        site:
                          street: 100 Example Street
                          city: Sacramento
                          state: California
                          stateCode: CA
                          zipCode: "95814"
                        utility:
                          name: Pacific Gas and Electric
                        existingSolarOnProperty: false
                        installer:
                          externalId: crm-10442
                          salesRepName: Riley Rep
                          salesRepEmail: riley@installer.example
                          submittedByEmail: riley@installer.example
                        dates:
                          onboarded: "2026-11-02"
                          contractSigned: "2026-10-30"
                          icApproval: null
                          icPayment: null
                          pto: null
                          pcApproval: null
                          pcPayment: null
                          forecastedInstall: "2026-12-04"
                          forecastedPto: null
                        approvals:
                          ic:
                            status: not_started
                            date: null
                          pc:
                            status: not_started
                            date: null
                        financials:
                          epcAmount: 30000
                          eligibleRoofingCost: 0
                          adjustedEpcAmount: 30000
                          ineligibleRoofingCost: 0
                          replacementCost: 30000
                          leaseFactor: 1.4285714
                          discountedAmount: 21000
                          baselineLeaseAmount: 21000
                          stateIncentive: null
                          utilityIncentive: null
                          netAmountDue: 21000
                          pePayout: 9000
                          icPayment: 6000
                          pcPayment: 3000
                          dcBonusRecipient: Installer
                          lender: null
                          amountFinanced: null
                          insuranceOption: "1"
                          insuranceRiskAdjustment: 0
                          salesTaxRate: 0
                          salesTaxAmount: 0
                        safeHarbor:
                          opportunityId: null
                        system:
                          type: Solar Only
                          sizeKw: 8.6
                          storageKwh: null
                          equipment:
                            - category: module
                              avlItemId: avl_8Hc2Kd91LmQ4
                              name: Qcells - Q.TRON BLK M-G2+ 430
                              manufacturer: Qcells
                              model: Q.TRON BLK M-G2+ 430
                              quantity: 20
                            - category: inverter
                              avlItemId: avl_3Pq7Rt55XyZ2
                              name: Enphase - IQ8M-72-2-US
                              manufacturer: Enphase
                              model: IQ8M-72-2-US
                              quantity: 20
                        documents:
                          required: 13
                          uploaded: 3
                          approved: 1
                          actionRequired: 1
                        photos:
                          sectionsRequired: 8
                          sectionsMissing:
                            - pv_array_wide
                            - racking
                          reviewStatus: null
                        actions:
                          open: 1
                          total: 2
                        editability:
                          fieldsLocked: false
                          reason: null
                          changeOrderRequiredAfterIc: false
                          externalIdEditable: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, PROJECT_LOCKED, PROJECT_CHANGED_SINCE_READ, CHANGE_ORDER_BLOCKED, EXTERNAL_ID_TAKEN."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                PROJECT_LOCKED:
                  $ref: "#/components/examples/Error_PROJECT_LOCKED"
                PROJECT_CHANGED_SINCE_READ:
                  $ref: "#/components/examples/Error_PROJECT_CHANGED_SINCE_READ"
                CHANGE_ORDER_BLOCKED:
                  $ref: "#/components/examples/Error_CHANGE_ORDER_BLOCKED"
                EXTERNAL_ID_TAKEN:
                  $ref: "#/components/examples/Error_EXTERNAL_ID_TAKEN"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: FIELD_NOT_EDITABLE, UTILITY_NOT_RECOGNIZED, PROJECT_UPDATE_REJECTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                FIELD_NOT_EDITABLE:
                  $ref: "#/components/examples/Error_FIELD_NOT_EDITABLE"
                UTILITY_NOT_RECOGNIZED:
                  $ref: "#/components/examples/Error_UTILITY_NOT_RECOGNIZED"
                PROJECT_UPDATE_REJECTED:
                  $ref: "#/components/examples/Error_PROJECT_UPDATE_REJECTED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:write
      x-pe-scope: projects:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/financials:
    put:
      operationId: updateProjectFinancials
      tags:
        - Projects
      summary: Update the financials
      description: |-
        Set the EPC (or the target Net Amount Due), roofing, insurance option, Domestic Content bonus recipient and lender. PE recomputes the whole pricing chain the way the portal's Edit Financials does. Every equipment item must be matched to the AVL first. Distributed Microgrid financials are set by PE and cannot change here. Use `?dryRun=true` to see the new chain without a write.

        **Scope:** `projects:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`FINANCIALS_SET_BY_PE`](#error-FINANCIALS_SET_BY_PE), [`PROJECT_LOCKED`](#error-PROJECT_LOCKED), [`PROJECT_CHANGED_SINCE_READ`](#error-PROJECT_CHANGED_SINCE_READ), [`CHANGE_ORDER_REQUIRED`](#error-CHANGE_ORDER_REQUIRED), [`CHANGE_ORDER_BLOCKED`](#error-CHANGE_ORDER_BLOCKED), [`FINANCIALS_INVALID`](#error-FINANCIALS_INVALID), [`FINANCIALS_EQUIPMENT_UNRESOLVED`](#error-FINANCIALS_EQUIPMENT_UNRESOLVED), [`PROJECT_UPDATE_REJECTED`](#error-PROJECT_UPDATE_REJECTED), [`EPC_OUT_OF_RANGE`](#error-EPC_OUT_OF_RANGE), [`LENDER_NOT_APPROVED`](#error-LENDER_NOT_APPROVED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: dryRun
          in: query
          required: false
          description: "true: check the change and return the result without a write."
          schema:
            type: string
            enum:
              - "true"
              - "false"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FinancialsRequest"
            examples:
              example:
                summary: Example
                value:
                  basis: epc
                  epcAmount: 31500
                  eligibleRoofingCost: 2000
                  ineligibleRoofingCost: 6000
                  insuranceOption: "1"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FinancialsResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      basis: epc
                      dryRun: false
                      changed: true
                      changedFields:
                        - financials.epcAmount
                        - financials.eligibleRoofingCost
                        - financials.ineligibleRoofingCost
                      changeOrder:
                        required: false
                        actionIds: []
                      financials:
                        epcAmount: 30000
                        eligibleRoofingCost: 0
                        adjustedEpcAmount: 30000
                        ineligibleRoofingCost: 0
                        replacementCost: 30000
                        leaseFactor: 1.4285714
                        discountedAmount: 21000
                        baselineLeaseAmount: 21000
                        stateIncentive: null
                        utilityIncentive: null
                        netAmountDue: 21000
                        pePayout: 9000
                        icPayment: 6000
                        pcPayment: 3000
                        dcBonusRecipient: Installer
                        lender: null
                        amountFinanced: null
                        insuranceOption: "1"
                        insuranceRiskAdjustment: 0
                        salesTaxRate: 0
                        salesTaxAmount: 0
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, FINANCIALS_SET_BY_PE, PROJECT_LOCKED, PROJECT_CHANGED_SINCE_READ, CHANGE_ORDER_REQUIRED, CHANGE_ORDER_BLOCKED, FINANCIALS_EQUIPMENT_UNRESOLVED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                FINANCIALS_SET_BY_PE:
                  $ref: "#/components/examples/Error_FINANCIALS_SET_BY_PE"
                PROJECT_LOCKED:
                  $ref: "#/components/examples/Error_PROJECT_LOCKED"
                PROJECT_CHANGED_SINCE_READ:
                  $ref: "#/components/examples/Error_PROJECT_CHANGED_SINCE_READ"
                CHANGE_ORDER_REQUIRED:
                  $ref: "#/components/examples/Error_CHANGE_ORDER_REQUIRED"
                CHANGE_ORDER_BLOCKED:
                  $ref: "#/components/examples/Error_CHANGE_ORDER_BLOCKED"
                FINANCIALS_EQUIPMENT_UNRESOLVED:
                  $ref: "#/components/examples/Error_FINANCIALS_EQUIPMENT_UNRESOLVED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: FINANCIALS_INVALID, PROJECT_UPDATE_REJECTED, EPC_OUT_OF_RANGE, LENDER_NOT_APPROVED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                FINANCIALS_INVALID:
                  $ref: "#/components/examples/Error_FINANCIALS_INVALID"
                PROJECT_UPDATE_REJECTED:
                  $ref: "#/components/examples/Error_PROJECT_UPDATE_REJECTED"
                EPC_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EPC_OUT_OF_RANGE"
                LENDER_NOT_APPROVED:
                  $ref: "#/components/examples/Error_LENDER_NOT_APPROVED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:write
      x-pe-scope: projects:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/equipment:
    put:
      operationId: updateProjectEquipment
      tags:
        - Projects
      summary: Update the equipment
      description: |-
        Set the equipment by category. Name each item by `avlItemId`, or by `name`: the exact AVL string, or a string on your Equipment Map. Send one item per category.

        | Category | AVL categories it accepts (GET /avl) | quantity |
        |---|---|---|
        | `module` | `pv_module`, `pv_combo` | The module count. |
        | `acModule` | `pv_combo` | The module count. |
        | `inverter` | `pv_inverter` | The inverter count. |
        | `racking` | `pv_racking` | Leave it out. |
        | `battery` | `bess` | The TOTAL battery units: lead and expansion units together. |
        | `batteryExpansion` | `bess` | Leave it out (the battery quantity counts it). |

        `pv_railing` and `pv_fasteners` items are not project equipment. Sending a quantity for `racking` or `batteryExpansion` returns `VALIDATION_FAILED`. A `module` or `acModule` quantity above 500 returns `EQUIPMENT_QUANTITY_OUT_OF_RANGE`. A `battery` or `batteryExpansion` item on a Solar Only project without a battery returns `SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER`: a battery changes the system type, which needs a change order.

        An unknown item returns `EQUIPMENT_NOT_ON_AVL` with up to 3 suggestions per item. A name that matches more than one item returns `EQUIPMENT_AMBIGUOUS` with the candidates. Use `?dryRun=true` to check the match first.

        **Scope:** `projects:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`PROJECT_LOCKED`](#error-PROJECT_LOCKED), [`PROJECT_CHANGED_SINCE_READ`](#error-PROJECT_CHANGED_SINCE_READ), [`CHANGE_ORDER_REQUIRED`](#error-CHANGE_ORDER_REQUIRED), [`CHANGE_ORDER_BLOCKED`](#error-CHANGE_ORDER_BLOCKED), [`EQUIPMENT_NOT_ON_AVL`](#error-EQUIPMENT_NOT_ON_AVL), [`EQUIPMENT_AMBIGUOUS`](#error-EQUIPMENT_AMBIGUOUS), [`EQUIPMENT_WRONG_CATEGORY`](#error-EQUIPMENT_WRONG_CATEGORY), [`EQUIPMENT_INVALID`](#error-EQUIPMENT_INVALID), [`EQUIPMENT_DOCUMENTS_SIGNED`](#error-EQUIPMENT_DOCUMENTS_SIGNED), [`PROJECT_UPDATE_REJECTED`](#error-PROJECT_UPDATE_REJECTED), [`SYSTEM_SIZE_LOOKS_LIKE_WATTS`](#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS), [`SYSTEM_SIZE_OUT_OF_RANGE`](#error-SYSTEM_SIZE_OUT_OF_RANGE), [`SYSTEM_SIZE_MISMATCH`](#error-SYSTEM_SIZE_MISMATCH), [`EQUIPMENT_QUANTITY_OUT_OF_RANGE`](#error-EQUIPMENT_QUANTITY_OUT_OF_RANGE), [`SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER`](#error-SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: dryRun
          in: query
          required: false
          description: "true: check the change and return the result without a write."
          schema:
            type: string
            enum:
              - "true"
              - "false"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EquipmentRequest"
            examples:
              example:
                summary: Example
                value:
                  items:
                    - category: module
                      avlItemId: avl_8Hc2Kd91LmQ4
                      quantity: 20
                    - category: inverter
                      name: Enphase - IQ8M-72-2-US
                      quantity: 20
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EquipmentResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      dryRun: false
                      changed: true
                      changedFields:
                        - assets.equipment.moduleSku
                      items:
                        - category: module
                          avlItemId: avl_8Hc2Kd91LmQ4
                          name: Qcells - Q.TRON BLK M-G2+ 430
                          matchedBy: avl_item_id
                        - category: inverter
                          avlItemId: avl_3Pq7Rt55XyZ2
                          name: Enphase - IQ8M-72-2-US
                          matchedBy: exact
                      changeOrder:
                        required: false
                        actionIds: []
                      system:
                        type: Solar Only
                        sizeKw: 8.6
                        storageKwh: null
                        equipment:
                          - category: module
                            avlItemId: avl_8Hc2Kd91LmQ4
                            name: Qcells - Q.TRON BLK M-G2+ 430
                            manufacturer: Qcells
                            model: Q.TRON BLK M-G2+ 430
                            quantity: 20
                          - category: inverter
                            avlItemId: avl_3Pq7Rt55XyZ2
                            name: Enphase - IQ8M-72-2-US
                            manufacturer: Enphase
                            model: IQ8M-72-2-US
                            quantity: 20
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, PROJECT_LOCKED, PROJECT_CHANGED_SINCE_READ, CHANGE_ORDER_REQUIRED, CHANGE_ORDER_BLOCKED, EQUIPMENT_DOCUMENTS_SIGNED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                PROJECT_LOCKED:
                  $ref: "#/components/examples/Error_PROJECT_LOCKED"
                PROJECT_CHANGED_SINCE_READ:
                  $ref: "#/components/examples/Error_PROJECT_CHANGED_SINCE_READ"
                CHANGE_ORDER_REQUIRED:
                  $ref: "#/components/examples/Error_CHANGE_ORDER_REQUIRED"
                CHANGE_ORDER_BLOCKED:
                  $ref: "#/components/examples/Error_CHANGE_ORDER_BLOCKED"
                EQUIPMENT_DOCUMENTS_SIGNED:
                  $ref: "#/components/examples/Error_EQUIPMENT_DOCUMENTS_SIGNED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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_WRONG_CATEGORY, EQUIPMENT_INVALID, PROJECT_UPDATE_REJECTED, SYSTEM_SIZE_LOOKS_LIKE_WATTS, SYSTEM_SIZE_OUT_OF_RANGE, SYSTEM_SIZE_MISMATCH, EQUIPMENT_QUANTITY_OUT_OF_RANGE, SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                EQUIPMENT_WRONG_CATEGORY:
                  $ref: "#/components/examples/Error_EQUIPMENT_WRONG_CATEGORY"
                EQUIPMENT_INVALID:
                  $ref: "#/components/examples/Error_EQUIPMENT_INVALID"
                PROJECT_UPDATE_REJECTED:
                  $ref: "#/components/examples/Error_PROJECT_UPDATE_REJECTED"
                SYSTEM_SIZE_LOOKS_LIKE_WATTS:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_LOOKS_LIKE_WATTS"
                SYSTEM_SIZE_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_OUT_OF_RANGE"
                SYSTEM_SIZE_MISMATCH:
                  $ref: "#/components/examples/Error_SYSTEM_SIZE_MISMATCH"
                EQUIPMENT_QUANTITY_OUT_OF_RANGE:
                  $ref: "#/components/examples/Error_EQUIPMENT_QUANTITY_OUT_OF_RANGE"
                SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER:
                  $ref: "#/components/examples/Error_SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:write
      x-pe-scope: projects:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/safe-harbor:
    put:
      operationId: setProjectSafeHarbor
      tags:
        - Projects
      summary: Link a Safe Harbor opportunity
      description: |-
        Link the project to one of your Safe Harbor opportunities, or send `null` to unlink it. The opportunity must be open, have units left and fit the project. After the project used units (at IC approval), you cannot unlink it. Safe Harbor does not apply to Distributed Microgrid projects (`SAFE_HARBOR_NOT_FOR_DM`). Use `?dryRun=true` to run every check without a write: `project` then shows the link as it would be.

        **Scope:** `projects:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`SAFE_HARBOR_NOT_FOR_DM`](#error-SAFE_HARBOR_NOT_FOR_DM), [`PROJECT_LOCKED`](#error-PROJECT_LOCKED), [`PROJECT_CHANGED_SINCE_READ`](#error-PROJECT_CHANGED_SINCE_READ), [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND), [`SAFE_HARBOR_WRONG_INSTALLER`](#error-SAFE_HARBOR_WRONG_INSTALLER), [`SAFE_HARBOR_OPPORTUNITY_CLOSED`](#error-SAFE_HARBOR_OPPORTUNITY_CLOSED), [`SAFE_HARBOR_NO_UNITS`](#error-SAFE_HARBOR_NO_UNITS), [`SAFE_HARBOR_NOT_APPLICABLE`](#error-SAFE_HARBOR_NOT_APPLICABLE), [`SAFE_HARBOR_CONSUMED`](#error-SAFE_HARBOR_CONSUMED), [`CHANGE_ORDER_BLOCKED`](#error-CHANGE_ORDER_BLOCKED), [`PROJECT_UPDATE_REJECTED`](#error-PROJECT_UPDATE_REJECTED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: dryRun
          in: query
          required: false
          description: "true: check the change and return the result without a write."
          schema:
            type: string
            enum:
              - "true"
              - "false"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SafeHarborRequest"
            examples:
              example:
                summary: Example
                value:
                  opportunityId: SHO-0042
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SafeHarborResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      changed: true
                      safeHarbor:
                        opportunityId: SHO-0042
                      previousOpportunityId: null
                      project:
                        projectId: CA2611-SMIT1
                        externalId: crm-10442
                        status: Active
                        deleted: false
                        milestone: Project Onboarded
                        documentReviewStatus: Action Required (Installer)
                        productType: Synthetic Cash
                        contractType: installer_originated
                        source:
                          channel: INSTALLER_API
                          grantId: igr_4bT9xQ2mK7pL1sV8nR3c
                        createdAt: "2026-11-02T17:20:04.000Z"
                        updatedAt: "2026-11-10T21:14:55.000Z"
                        customer:
                          firstName: Jordan
                          lastName: Example
                          email: jordan@example.com
                          phone: 555-010-0199
                          mailingSameAsSite: true
                        site:
                          street: 100 Example Street
                          city: Sacramento
                          state: California
                          stateCode: CA
                          zipCode: "95814"
                        utility:
                          name: Pacific Gas and Electric
                        existingSolarOnProperty: false
                        installer:
                          externalId: crm-10442
                          salesRepName: Riley Rep
                          salesRepEmail: riley@installer.example
                          submittedByEmail: riley@installer.example
                        dates:
                          onboarded: "2026-11-02"
                          contractSigned: "2026-10-30"
                          icApproval: null
                          icPayment: null
                          pto: null
                          pcApproval: null
                          pcPayment: null
                          forecastedInstall: "2026-12-04"
                          forecastedPto: null
                        approvals:
                          ic:
                            status: not_started
                            date: null
                          pc:
                            status: not_started
                            date: null
                        financials:
                          epcAmount: 30000
                          eligibleRoofingCost: 0
                          adjustedEpcAmount: 30000
                          ineligibleRoofingCost: 0
                          replacementCost: 30000
                          leaseFactor: 1.4285714
                          discountedAmount: 21000
                          baselineLeaseAmount: 21000
                          stateIncentive: null
                          utilityIncentive: null
                          netAmountDue: 21000
                          pePayout: 9000
                          icPayment: 6000
                          pcPayment: 3000
                          dcBonusRecipient: Installer
                          lender: null
                          amountFinanced: null
                          insuranceOption: "1"
                          insuranceRiskAdjustment: 0
                          salesTaxRate: 0
                          salesTaxAmount: 0
                        safeHarbor:
                          opportunityId: null
                        system:
                          type: Solar Only
                          sizeKw: 8.6
                          storageKwh: null
                          equipment:
                            - category: module
                              avlItemId: avl_8Hc2Kd91LmQ4
                              name: Qcells - Q.TRON BLK M-G2+ 430
                              manufacturer: Qcells
                              model: Q.TRON BLK M-G2+ 430
                              quantity: 20
                            - category: inverter
                              avlItemId: avl_3Pq7Rt55XyZ2
                              name: Enphase - IQ8M-72-2-US
                              manufacturer: Enphase
                              model: IQ8M-72-2-US
                              quantity: 20
                        documents:
                          required: 13
                          uploaded: 3
                          approved: 1
                          actionRequired: 1
                        photos:
                          sectionsRequired: 8
                          sectionsMissing:
                            - pv_array_wide
                            - racking
                          reviewStatus: null
                        actions:
                          open: 1
                          total: 2
                        editability:
                          fieldsLocked: false
                          reason: null
                          changeOrderRequiredAfterIc: false
                          externalIdEditable: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND, SAFE_HARBOR_OPPORTUNITY_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
                SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, SAFE_HARBOR_NOT_FOR_DM, PROJECT_LOCKED, PROJECT_CHANGED_SINCE_READ, SAFE_HARBOR_OPPORTUNITY_CLOSED, SAFE_HARBOR_NO_UNITS, SAFE_HARBOR_CONSUMED, CHANGE_ORDER_BLOCKED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                SAFE_HARBOR_NOT_FOR_DM:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_NOT_FOR_DM"
                PROJECT_LOCKED:
                  $ref: "#/components/examples/Error_PROJECT_LOCKED"
                PROJECT_CHANGED_SINCE_READ:
                  $ref: "#/components/examples/Error_PROJECT_CHANGED_SINCE_READ"
                SAFE_HARBOR_OPPORTUNITY_CLOSED:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_OPPORTUNITY_CLOSED"
                SAFE_HARBOR_NO_UNITS:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_NO_UNITS"
                SAFE_HARBOR_CONSUMED:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_CONSUMED"
                CHANGE_ORDER_BLOCKED:
                  $ref: "#/components/examples/Error_CHANGE_ORDER_BLOCKED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: SAFE_HARBOR_WRONG_INSTALLER, SAFE_HARBOR_NOT_APPLICABLE, PROJECT_UPDATE_REJECTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SAFE_HARBOR_WRONG_INSTALLER:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_WRONG_INSTALLER"
                SAFE_HARBOR_NOT_APPLICABLE:
                  $ref: "#/components/examples/Error_SAFE_HARBOR_NOT_APPLICABLE"
                PROJECT_UPDATE_REJECTED:
                  $ref: "#/components/examples/Error_PROJECT_UPDATE_REJECTED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:write
      x-pe-scope: projects:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/activity:
    get:
      operationId: listProjectActivity
      tags:
        - Projects
      summary: List the activity of a project
      description: |-
        List the project's activity, newest first: the same entries the Activity tab of the Installer Portal shows. PE leaves out internal system entries. The cursor is opaque. Entries that share a timestamp are never skipped across pages. A cursor from before 2026-11-12 no longer works (`CURSOR_INVALID`); start again without one.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`CURSOR_INVALID`](#error-CURSOR_INVALID).
      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 (SBX-... in the Test environment).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1 to 100. Default 50.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          description: The nextCursor of the previous page. Send the same filters.
          schema:
            type: string
            maxLength: 200
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivityPageResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      activity:
                        - date: "2026-11-10T21:14:55.000Z"
                          activityBy: Riley Rep
                          type: Document Uploaded
                          category: document_review
                          notes: Uploaded Utility Bill (version 2).
                          document:
                            type: document
                            label: Utility Bill
                      nextCursor: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, VALIDATION_FAILED, UNKNOWN_FIELD, CURSOR_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
                CURSOR_INVALID:
                  $ref: "#/components/examples/Error_CURSOR_INVALID"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/{projectId}/documents:
    get:
      operationId: listProjectDocuments
      tags:
        - Documents
      summary: List the documents of a project
      description: |-
        List every document slot of the project: required or optional, IC or PC stage, review status, versions, whether uploads are open, the automated review result (`sibyl`), the open Actions of the slot and the latest review activity. See Documents.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      documents:
                        - documentType: utilityBill
                          label: Utility Bill
                          required: true
                          blocking: true
                          stage: ic
                          requestedAt: Project Onboarded
                          reviewStatus: Response Needed
                          submittedAt: "2026-11-02"
                          reviewerComments: null
                          uploadOpen: true
                          uploadClosedReason: null
                          acceptedContentTypes:
                            - application/pdf
                            - image/jpeg
                            - image/png
                            - image/heic
                            - image/heif
                          maxFileBytes: 52428800
                          currentVersion: 1
                          versions:
                            - version: 1
                              fileName: bill.pdf
                              contentType: application/pdf
                              uploadedAt: "2026-11-02T17:22:00.000Z"
                              uploadedBy: Riley Rep
                              source: installer_api
                              archived: false
                              current: true
                          sibyl:
                            state: null
                            reviewedAt: null
                          openActions:
                            - actionId: act_7Gm2Qp9xVb4
                              severity: fail
                              title: MISS-INIT-CUST
                              description: The customer initials are missing on page 3 of the Customer Agreement (Section 9, Arbitration).
                              nextStep: Upload a copy of the Customer Agreement with every initial box completed.
                              category: sibyl
                          reviewActivity: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/{projectId}/documents/{documentType}/versions/{version}/download:
    get:
      operationId: getDocumentDownloadUrl
      tags:
        - Documents
      summary: Get a download URL
      description: |-
        Get a signed URL for one version of a document. The URL is valid for 15 minutes. Read `version` numbers from `GET /projects/{projectId}/documents`.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
        - name: documentType
          in: path
          required: true
          description: The document type, for example signedFinalPermit. GET /projects/{projectId}/documents lists them.
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: The version number of the document.
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentDownloadResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      documentType: utilityBill
                      version: 1
                      fileName: bill.pdf
                      contentType: application/pdf
                      archived: false
                      downloadUrl: https://storage.googleapis.com/...?X-Goog-Signature=...
                      expiresAt: "2026-11-11T18:17:11.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/{projectId}/documents/{documentType}/uploads:
    post:
      operationId: createDocumentUpload
      tags:
        - Documents
      summary: Create a document upload
      description: |-
        Start a document upload to a slot. The response has a signed `uploadUrl` valid for 15 minutes. PUT the file with every header in `uploadHeaders`, then confirm. Each call counts one file toward the daily file upload limit. For photos use the photo endpoints. For Access to Monitoring use `PUT /projects/{projectId}/monitoring-access`.

        **Scope:** `documents:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`DOCUMENT_TYPE_NOT_UPLOADABLE`](#error-DOCUMENT_TYPE_NOT_UPLOADABLE), [`PHOTOS_USE_PHOTO_UPLOAD`](#error-PHOTOS_USE_PHOTO_UPLOAD), [`DOCUMENT_UPLOAD_CLOSED`](#error-DOCUMENT_UPLOAD_CLOSED), [`CONTENT_TYPE_NOT_ALLOWED`](#error-CONTENT_TYPE_NOT_ALLOWED), [`DAILY_QUOTA_EXCEEDED`](#error-DAILY_QUOTA_EXCEEDED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: documentType
          in: path
          required: true
          description: The document type, for example signedFinalPermit. GET /projects/{projectId}/documents lists them.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDocumentUploadRequest"
            examples:
              example:
                summary: Example
                value:
                  fileName: final-permit.pdf
                  contentType: application/pdf
      responses:
        "201":
          description: Created.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedDocumentUploadResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      documentType: signedFinalPermit
                      fileUploadId: ifu_Q8w2Er5Ty7Ui9Op1As3D
                      uploadUrl: https://storage.googleapis.com/...?X-Goog-Signature=...
                      uploadMethod: PUT
                      uploadHeaders:
                        Content-Type: application/pdf
                        x-goog-if-generation-match: "0"
                        x-goog-content-length-range: 0,52428800
                      maxBytes: 52428800
                      expiresAt: "2026-11-11T18:17:11.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, DOCUMENT_UPLOAD_CLOSED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                DOCUMENT_UPLOAD_CLOSED:
                  $ref: "#/components/examples/Error_DOCUMENT_UPLOAD_CLOSED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: DOCUMENT_TYPE_NOT_UPLOADABLE, PHOTOS_USE_PHOTO_UPLOAD, CONTENT_TYPE_NOT_ALLOWED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DOCUMENT_TYPE_NOT_UPLOADABLE:
                  $ref: "#/components/examples/Error_DOCUMENT_TYPE_NOT_UPLOADABLE"
                PHOTOS_USE_PHOTO_UPLOAD:
                  $ref: "#/components/examples/Error_PHOTOS_USE_PHOTO_UPLOAD"
                CONTENT_TYPE_NOT_ALLOWED:
                  $ref: "#/components/examples/Error_CONTENT_TYPE_NOT_ALLOWED"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED, DAILY_QUOTA_EXCEEDED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            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":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - documents:write
      x-pe-scope: documents:write
      x-pe-rate-limit-bucket: upload
      x-pe-actor: required
  /projects/{projectId}/documents/{documentType}/uploads/{fileUploadId}/confirm:
    post:
      operationId: confirmDocumentUpload
      tags:
        - Documents
      summary: Confirm a document upload
      description: |-
        Tell PE that the file is in place. PE checks the size and the first bytes, adds a new version, sets the slot to review and starts the automated review where it applies (`reviewQueued`). List the Actions this file answers in `resolveActionIds`. A repeated confirm returns the same version, so it is safe to retry. If the first confirm saved the file but its answer was lost, the retry returns the existing version with `reviewQueued: false`; the review of that version is already queued.

        **Scope:** `documents:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`DOCUMENT_TYPE_NOT_UPLOADABLE`](#error-DOCUMENT_TYPE_NOT_UPLOADABLE), [`PHOTOS_USE_PHOTO_UPLOAD`](#error-PHOTOS_USE_PHOTO_UPLOAD), [`DOCUMENT_UPLOAD_CLOSED`](#error-DOCUMENT_UPLOAD_CLOSED), [`DOCUMENT_LOCKED`](#error-DOCUMENT_LOCKED), [`FILE_NOT_RECEIVED`](#error-FILE_NOT_RECEIVED), [`FILE_UPLOAD_EXPIRED`](#error-FILE_UPLOAD_EXPIRED), [`FILE_UPLOAD_IN_PROGRESS`](#error-FILE_UPLOAD_IN_PROGRESS), [`FILE_TOO_LARGE`](#error-FILE_TOO_LARGE), [`FILE_CONTENT_MISMATCH`](#error-FILE_CONTENT_MISMATCH), [`FILE_EMPTY`](#error-FILE_EMPTY).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: documentType
          in: path
          required: true
          description: The document type, for example signedFinalPermit. GET /projects/{projectId}/documents lists them.
          schema:
            type: string
        - name: fileUploadId
          in: path
          required: true
          description: The upload id from the create call (ifu_...).
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmUploadRequest"
            examples:
              example:
                summary: Example
                value:
                  notes: Corrected permit with the inspector's signature.
                  resolveActionIds:
                    - act_7Gm2Qp9xVb4
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfirmedDocumentUploadResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      documentType: signedFinalPermit
                      fileUploadId: ifu_Q8w2Er5Ty7Ui9Op1As3D
                      version: 2
                      reviewStatus: Pending Review
                      reviewQueued: true
                      resolvedActionIds:
                        - act_7Gm2Qp9xVb4
                      skippedActionIds: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, DOCUMENT_UPLOAD_CLOSED, DOCUMENT_LOCKED, FILE_NOT_RECEIVED, FILE_UPLOAD_IN_PROGRESS."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                DOCUMENT_UPLOAD_CLOSED:
                  $ref: "#/components/examples/Error_DOCUMENT_UPLOAD_CLOSED"
                DOCUMENT_LOCKED:
                  $ref: "#/components/examples/Error_DOCUMENT_LOCKED"
                FILE_NOT_RECEIVED:
                  $ref: "#/components/examples/Error_FILE_NOT_RECEIVED"
                FILE_UPLOAD_IN_PROGRESS:
                  $ref: "#/components/examples/Error_FILE_UPLOAD_IN_PROGRESS"
        "410":
          description: "Gone. Codes: FILE_UPLOAD_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                FILE_UPLOAD_EXPIRED:
                  $ref: "#/components/examples/Error_FILE_UPLOAD_EXPIRED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: DOCUMENT_TYPE_NOT_UPLOADABLE, PHOTOS_USE_PHOTO_UPLOAD, FILE_TOO_LARGE, FILE_CONTENT_MISMATCH, FILE_EMPTY."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DOCUMENT_TYPE_NOT_UPLOADABLE:
                  $ref: "#/components/examples/Error_DOCUMENT_TYPE_NOT_UPLOADABLE"
                PHOTOS_USE_PHOTO_UPLOAD:
                  $ref: "#/components/examples/Error_PHOTOS_USE_PHOTO_UPLOAD"
                FILE_TOO_LARGE:
                  $ref: "#/components/examples/Error_FILE_TOO_LARGE"
                FILE_CONTENT_MISMATCH:
                  $ref: "#/components/examples/Error_FILE_CONTENT_MISMATCH"
                FILE_EMPTY:
                  $ref: "#/components/examples/Error_FILE_EMPTY"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - documents:write
      x-pe-scope: documents:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/documents/{documentType}/versions/{version}/archive:
    post:
      operationId: archiveDocumentVersion
      tags:
        - Documents
      summary: Archive a document version
      description: |-
        Archive every version that is not valid. A version is not valid when it is the wrong file, when it belongs to a different project, or when a newer version replaces it. You must archive these versions: SIBYL reviews every version that is not archived, and an invalid version that stays active can cause review errors and Actions on the project. PE keeps the file. Add a `reason`.

        **Scope:** `documents:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`DOCUMENT_TYPE_NOT_UPLOADABLE`](#error-DOCUMENT_TYPE_NOT_UPLOADABLE), [`DOCUMENT_ARCHIVE_BLOCKED`](#error-DOCUMENT_ARCHIVE_BLOCKED), [`DOCUMENT_LOCKED`](#error-DOCUMENT_LOCKED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: documentType
          in: path
          required: true
          description: The document type, for example signedFinalPermit. GET /projects/{projectId}/documents lists them.
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: The version number of the document.
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArchiveRequest"
            examples:
              example:
                summary: Example
                value:
                  reason: Uploaded to the wrong project.
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArchiveResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      documentType: utilityBill
                      version: 1
                      archived: true
                      changed: true
                      currentChanged: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, DOCUMENT_ARCHIVE_BLOCKED, DOCUMENT_LOCKED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                DOCUMENT_ARCHIVE_BLOCKED:
                  $ref: "#/components/examples/Error_DOCUMENT_ARCHIVE_BLOCKED"
                DOCUMENT_LOCKED:
                  $ref: "#/components/examples/Error_DOCUMENT_LOCKED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: DOCUMENT_TYPE_NOT_UPLOADABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DOCUMENT_TYPE_NOT_UPLOADABLE:
                  $ref: "#/components/examples/Error_DOCUMENT_TYPE_NOT_UPLOADABLE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - documents:write
      x-pe-scope: documents:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/documents/{documentType}/versions/{version}/restore:
    post:
      operationId: restoreDocumentVersion
      tags:
        - Documents
      summary: Restore a document version
      description: |-
        Restore an archived version.

        **Scope:** `documents:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`DOCUMENT_TYPE_NOT_UPLOADABLE`](#error-DOCUMENT_TYPE_NOT_UPLOADABLE), [`DOCUMENT_ARCHIVE_BLOCKED`](#error-DOCUMENT_ARCHIVE_BLOCKED), [`DOCUMENT_LOCKED`](#error-DOCUMENT_LOCKED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: documentType
          in: path
          required: true
          description: The document type, for example signedFinalPermit. GET /projects/{projectId}/documents lists them.
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: The version number of the document.
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArchiveRequest"
            examples:
              example:
                summary: Example
                value: {}
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArchiveResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      documentType: utilityBill
                      version: 1
                      archived: false
                      changed: true
                      currentChanged: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, DOCUMENT_ARCHIVE_BLOCKED, DOCUMENT_LOCKED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                DOCUMENT_ARCHIVE_BLOCKED:
                  $ref: "#/components/examples/Error_DOCUMENT_ARCHIVE_BLOCKED"
                DOCUMENT_LOCKED:
                  $ref: "#/components/examples/Error_DOCUMENT_LOCKED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: DOCUMENT_TYPE_NOT_UPLOADABLE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                DOCUMENT_TYPE_NOT_UPLOADABLE:
                  $ref: "#/components/examples/Error_DOCUMENT_TYPE_NOT_UPLOADABLE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - documents:write
      x-pe-scope: documents:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/photos:
    get:
      operationId: listProjectPhotos
      tags:
        - Photos
      summary: List the photos of a project
      description: |-
        List the photo categories for the project's system type, the files in each category, the categories still missing (`sectionsMissing`), the review status and the open photo Actions. See Photos.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PhotoListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      systemType: Solar Only
                      reviewStatus: null
                      submittedAt: null
                      reviewerComments: null
                      uploadOpen: true
                      uploadClosedReason: null
                      acceptedContentTypes:
                        - application/pdf
                        - image/jpeg
                        - image/png
                        - image/heic
                        - image/heif
                        - image/webp
                        - image/gif
                      maxFileBytes: 104857600
                      maxFilesPerUpload: 25
                      sectionsMissing:
                        - category: racking
                          label: Racking
                      coverageApplies: true
                      categories:
                        - category: site_address
                          label: Site Address
                          description: Site address with the home in the background.
                          required: true
                          covered: true
                          files:
                            - version: 1
                              fileName: front.jpg
                              contentType: image/jpeg
                              uploadedAt: "2026-11-04T16:00:00.000Z"
                              uploadedBy: Riley Rep
                              archived: false
                              batchId: ifu_Z1x2C3v4B5n6M7a8S9d0
                      openActions: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/{projectId}/photos/{category}/uploads:
    post:
      operationId: createPhotoUpload
      tags:
        - Photos
      summary: Create a photo upload
      description: |-
        Start an upload of 1 to 25 photos to one category. Each file gets its own signed `uploadUrl`, valid for 15 minutes. PUT each file with its `uploadHeaders`, then confirm the batch. The files count toward the daily file upload limit.

        **Scope:** `documents:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`PHOTO_CATEGORY_UNKNOWN`](#error-PHOTO_CATEGORY_UNKNOWN), [`DOCUMENT_UPLOAD_CLOSED`](#error-DOCUMENT_UPLOAD_CLOSED), [`CONTENT_TYPE_NOT_ALLOWED`](#error-CONTENT_TYPE_NOT_ALLOWED), [`DAILY_QUOTA_EXCEEDED`](#error-DAILY_QUOTA_EXCEEDED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: category
          in: path
          required: true
          description: The photo category, for example racking.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePhotoUploadRequest"
            examples:
              example:
                summary: Example
                value:
                  files:
                    - fileName: racking-1.jpg
                      contentType: image/jpeg
                    - fileName: racking-2.jpg
                      contentType: image/jpeg
      responses:
        "201":
          description: Created.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedPhotoUploadResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      category: racking
                      batchId: ifu_P0o9I8u7Y6t5R4e3W2q1
                      files:
                        - index: 0
                          fileName: racking-1.jpg
                          uploadUrl: https://storage.googleapis.com/...?X-Goog-Signature=...
                          uploadMethod: PUT
                          uploadHeaders:
                            Content-Type: image/jpeg
                            x-goog-if-generation-match: "0"
                            x-goog-content-length-range: 0,104857600
                      maxBytes: 104857600
                      expiresAt: "2026-11-11T18:17:11.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, DOCUMENT_UPLOAD_CLOSED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                DOCUMENT_UPLOAD_CLOSED:
                  $ref: "#/components/examples/Error_DOCUMENT_UPLOAD_CLOSED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: PHOTO_CATEGORY_UNKNOWN, CONTENT_TYPE_NOT_ALLOWED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PHOTO_CATEGORY_UNKNOWN:
                  $ref: "#/components/examples/Error_PHOTO_CATEGORY_UNKNOWN"
                CONTENT_TYPE_NOT_ALLOWED:
                  $ref: "#/components/examples/Error_CONTENT_TYPE_NOT_ALLOWED"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED, DAILY_QUOTA_EXCEEDED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            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":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - documents:write
      x-pe-scope: documents:write
      x-pe-rate-limit-bucket: upload
      x-pe-actor: required
  /projects/{projectId}/photos/{category}/uploads/{batchId}/confirm:
    post:
      operationId: confirmPhotoUpload
      tags:
        - Photos
      summary: Confirm a photo upload
      description: |-
        Tell PE that the files are in place. PE checks each file, adds the photos to the category and, when every category has a file, sends the photos to review. A repeated confirm returns the same result.

        **Scope:** `documents:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`PHOTO_CATEGORY_UNKNOWN`](#error-PHOTO_CATEGORY_UNKNOWN), [`DOCUMENT_UPLOAD_CLOSED`](#error-DOCUMENT_UPLOAD_CLOSED), [`DOCUMENT_LOCKED`](#error-DOCUMENT_LOCKED), [`FILE_NOT_RECEIVED`](#error-FILE_NOT_RECEIVED), [`FILE_UPLOAD_EXPIRED`](#error-FILE_UPLOAD_EXPIRED), [`FILE_UPLOAD_IN_PROGRESS`](#error-FILE_UPLOAD_IN_PROGRESS), [`FILE_TOO_LARGE`](#error-FILE_TOO_LARGE), [`FILE_CONTENT_MISMATCH`](#error-FILE_CONTENT_MISMATCH), [`FILE_EMPTY`](#error-FILE_EMPTY).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: category
          in: path
          required: true
          description: The photo category, for example racking.
          schema:
            type: string
        - name: batchId
          in: path
          required: true
          description: The batch id from the create call (ifu_...).
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmUploadRequest"
            examples:
              example:
                summary: Example
                value:
                  notes: Racking labels and mill marks.
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfirmedPhotoUploadResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      category: racking
                      batchId: ifu_P0o9I8u7Y6t5R4e3W2q1
                      uploaded: 2
                      versions:
                        - 3
                        - 4
                      deduped: 0
                      sectionsMissing: []
                      reviewStatus: Pending Review
                      reviewQueued: false
                      resolvedActionIds: []
                      skippedActionIds: []
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, DOCUMENT_UPLOAD_CLOSED, DOCUMENT_LOCKED, FILE_NOT_RECEIVED, FILE_UPLOAD_IN_PROGRESS."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                DOCUMENT_UPLOAD_CLOSED:
                  $ref: "#/components/examples/Error_DOCUMENT_UPLOAD_CLOSED"
                DOCUMENT_LOCKED:
                  $ref: "#/components/examples/Error_DOCUMENT_LOCKED"
                FILE_NOT_RECEIVED:
                  $ref: "#/components/examples/Error_FILE_NOT_RECEIVED"
                FILE_UPLOAD_IN_PROGRESS:
                  $ref: "#/components/examples/Error_FILE_UPLOAD_IN_PROGRESS"
        "410":
          description: "Gone. Codes: FILE_UPLOAD_EXPIRED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                FILE_UPLOAD_EXPIRED:
                  $ref: "#/components/examples/Error_FILE_UPLOAD_EXPIRED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: PHOTO_CATEGORY_UNKNOWN, FILE_TOO_LARGE, FILE_CONTENT_MISMATCH, FILE_EMPTY."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PHOTO_CATEGORY_UNKNOWN:
                  $ref: "#/components/examples/Error_PHOTO_CATEGORY_UNKNOWN"
                FILE_TOO_LARGE:
                  $ref: "#/components/examples/Error_FILE_TOO_LARGE"
                FILE_CONTENT_MISMATCH:
                  $ref: "#/components/examples/Error_FILE_CONTENT_MISMATCH"
                FILE_EMPTY:
                  $ref: "#/components/examples/Error_FILE_EMPTY"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - documents:write
      x-pe-scope: documents:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/monitoring-access:
    get:
      operationId: getMonitoringAccess
      tags:
        - Monitoring access
      summary: Read monitoring access
      description: |-
        Read the monitoring sites of the project, the providers its equipment needs, and the result of PE's check for each site. See Monitoring access.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MonitoringAccessResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      required:
                        - role: inverter
                          provider: enphase
                          manufacturer: Enphase
                      anyProvider: false
                      notRequiredProviders: []
                      sites:
                        - provider: enphase
                          manufacturer: Enphase
                          siteId: "4410023"
                          siteName: null
                          roles:
                            - inverter
                          enteredAt: "2026-11-05T15:00:00.000Z"
                          verification:
                            status: pass
                            checkedAt: "2026-11-05T15:02:00.000Z"
                            checks:
                              - check: access
                                label: PE can access the site
                                status: pass
                                message: null
                      state: verified
                      reviewStatus: Pending Approval
                      lastRun:
                        status: done
                        requestedAt: "2026-11-05T15:00:00.000Z"
                        finishedAt: "2026-11-05T15:02:00.000Z"
                        outcome: verified
                      sitesEditable: true
                      icApproved: false
                      exceptionRequested: false
                      baseSitesHash: b1946ac92492d2347c6235b4d2611184
                      updatedAt: "2026-11-05T15:02:00.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
    put:
      operationId: setMonitoringAccess
      tags:
        - Monitoring access
      summary: Save monitoring site IDs
      description: |-
        Save all the monitoring sites of the project (up to 10). PE then checks each site. Send `baseSitesHash` from your last read so that you do not overwrite someone else's change.

        **Scope:** `documents:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED), [`MONITORING_ACCESS_INVALID`](#error-MONITORING_ACCESS_INVALID), [`MONITORING_SITE_DUPLICATE`](#error-MONITORING_SITE_DUPLICATE), [`MONITORING_ACCESS_CHANGED`](#error-MONITORING_ACCESS_CHANGED), [`MONITORING_ACCESS_LOCKED`](#error-MONITORING_ACCESS_LOCKED), [`MONITORING_ACCESS_RATE_LIMITED`](#error-MONITORING_ACCESS_RATE_LIMITED), [`MONITORING_ACCESS_NOT_ALLOWED`](#error-MONITORING_ACCESS_NOT_ALLOWED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MonitoringAccessRequest"
            examples:
              example:
                summary: Example
                value:
                  sites:
                    - provider: enphase
                      siteId: "4410023"
                  verify: now
                  baseSitesHash: b1946ac92492d2347c6235b4d2611184
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MonitoringAccessResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      state: verifying
                      acceptedActionIds: []
                      skippedActionIds: []
                      monitoringAccess:
                        required:
                          - role: inverter
                            provider: enphase
                            manufacturer: Enphase
                        anyProvider: false
                        notRequiredProviders: []
                        sites:
                          - provider: enphase
                            manufacturer: null
                            siteId: "4410023"
                            siteName: null
                            roles:
                              - inverter
                            enteredAt: "2026-11-11T18:02:11.000Z"
                            verification: null
                        state: verifying
                        reviewStatus: Pending Approval
                        lastRun:
                          status: queued
                          requestedAt: "2026-11-11T18:02:11.000Z"
                          finishedAt: null
                          outcome: null
                        sitesEditable: true
                        icApproved: false
                        exceptionRequested: false
                        baseSitesHash: 5d41402abc4b2a76b9719d911017c592
                        updatedAt: "2026-11-11T18:02:11.000Z"
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, MONITORING_ACCESS_NOT_ALLOWED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
                MONITORING_ACCESS_NOT_ALLOWED:
                  $ref: "#/components/examples/Error_MONITORING_ACCESS_NOT_ALLOWED"
        "404":
          description: "Not found. Codes: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED, MONITORING_SITE_DUPLICATE, MONITORING_ACCESS_CHANGED, MONITORING_ACCESS_LOCKED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
                MONITORING_SITE_DUPLICATE:
                  $ref: "#/components/examples/Error_MONITORING_SITE_DUPLICATE"
                MONITORING_ACCESS_CHANGED:
                  $ref: "#/components/examples/Error_MONITORING_ACCESS_CHANGED"
                MONITORING_ACCESS_LOCKED:
                  $ref: "#/components/examples/Error_MONITORING_ACCESS_LOCKED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: MONITORING_ACCESS_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                MONITORING_ACCESS_INVALID:
                  $ref: "#/components/examples/Error_MONITORING_ACCESS_INVALID"
        "429":
          description: "A limit was reached. Codes: RATE_LIMITED, MONITORING_ACCESS_RATE_LIMITED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Retry-After:
              $ref: "#/components/headers/Retry-After"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RATE_LIMITED:
                  $ref: "#/components/examples/Error_RATE_LIMITED"
                MONITORING_ACCESS_RATE_LIMITED:
                  $ref: "#/components/examples/Error_MONITORING_ACCESS_RATE_LIMITED"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - documents:write
      x-pe-scope: documents:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/actions:
    get:
      operationId: listProjectActions
      tags:
        - Actions
      summary: List the Actions of a project
      description: |-
        List the Actions of the project, newest first, with their notes and history. Filter by `status`.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Only Actions with this status.
          schema:
            type: string
            enum:
              - open
              - resolved
              - reject
              - ai_error
              - cannot_resolve
        - name: limit
          in: query
          required: false
          description: At most this many Actions. Default 200.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 200
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      actions:
                        - actionId: act_7Gm2Qp9xVb4
                          status: open
                          severity: fail
                          title: MISS-INIT-CUST
                          description: The customer initials are missing on page 3 of the Customer Agreement (Section 9, Arbitration).
                          code: MISS-INIT-CUST
                          resolution: Customer Resigns
                          nextStep: Upload a copy of the Customer Agreement with every initial box completed.
                          category: sibyl
                          documentType: customerAgreement
                          documentSlot: customerAgreement
                          pageRefs:
                            - 3
                          createdAt: "2026-11-02T17:31:10.000Z"
                          updatedAt: "2026-11-02T17:31:10.000Z"
                          resolvedAt: null
                          notes: []
                          history:
                            - kind: created
                              at: "2026-11-02T17:31:10.000Z"
                              by: SIBYL
                      counts:
                        total: 1
                        open: 1
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/{projectId}/actions/{actionId}:
    get:
      operationId: getProjectAction
      tags:
        - Actions
      summary: Read an Action
      description: |-
        Read one Action with its notes and history.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
        - name: actionId
          in: path
          required: true
          description: The Action id.
          schema:
            type: string
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionResponseResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      action:
                        actionId: act_7Gm2Qp9xVb4
                        status: open
                        severity: fail
                        title: MISS-INIT-CUST
                        description: The customer initials are missing on page 3 of the Customer Agreement (Section 9, Arbitration).
                        code: MISS-INIT-CUST
                        resolution: Customer Resigns
                        nextStep: Upload a copy of the Customer Agreement with every initial box completed.
                        category: sibyl
                        documentType: customerAgreement
                        documentSlot: customerAgreement
                        pageRefs:
                          - 3
                        createdAt: "2026-11-02T17:31:10.000Z"
                        updatedAt: "2026-11-02T17:31:10.000Z"
                        resolvedAt: null
                        notes: []
                        history:
                          - kind: created
                            at: "2026-11-02T17:31:10.000Z"
                            by: SIBYL
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
  /projects/{projectId}/actions/{actionId}/resolve:
    post:
      operationId: resolveProjectAction
      tags:
        - Actions
      summary: Resolve an Action
      description: |-
        Resolve an Action with a note that says what you did. The note is required and stays in the history. Resolving an Action that is already resolved changes nothing (`statusChanged: false`).

        **Scope:** `actions:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: actionId
          in: path
          required: true
          description: The Action id.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NoteRequest"
            examples:
              example:
                summary: Example
                value:
                  note: The customer initialed page 3. The new agreement is uploaded as version 2.
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionResolveResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      statusChanged: true
                      action:
                        actionId: act_7Gm2Qp9xVb4
                        status: resolved
                        severity: fail
                        title: MISS-INIT-CUST
                        description: The customer initials are missing on page 3 of the Customer Agreement (Section 9, Arbitration).
                        code: MISS-INIT-CUST
                        resolution: Customer Resigns
                        nextStep: Upload a copy of the Customer Agreement with every initial box completed.
                        category: sibyl
                        documentType: customerAgreement
                        documentSlot: customerAgreement
                        pageRefs:
                          - 3
                        createdAt: "2026-11-02T17:31:10.000Z"
                        updatedAt: "2026-11-02T17:31:10.000Z"
                        resolvedAt: "2026-11-11T18:02:11.482Z"
                        notes: []
                        history:
                          - kind: created
                            at: "2026-11-02T17:31:10.000Z"
                            by: SIBYL
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - actions:write
      x-pe-scope: actions:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /projects/{projectId}/actions/{actionId}/notes:
    post:
      operationId: addProjectActionNote
      tags:
        - Actions
      summary: Add a note to an Action
      description: |-
        Add a note to an Action without a status change. Notes cannot be changed or deleted.

        **Scope:** `actions:write`. **X-PE-Actor-Email:** required.

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email-Required"
        - name: projectId
          in: path
          required: true
          description: The PE Project ID (SBX-... in the Test environment).
          schema:
            type: string
        - name: actionId
          in: path
          required: true
          description: The Action id.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NoteRequest"
            examples:
              example:
                summary: Example
                value:
                  note: We asked the customer to sign again. Expected on Friday.
      responses:
        "201":
          description: Created.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionResponseResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: CA2611-SMIT1
                      action:
                        actionId: act_7Gm2Qp9xVb4
                        status: open
                        severity: fail
                        title: MISS-INIT-CUST
                        description: The customer initials are missing on page 3 of the Customer Agreement (Section 9, Arbitration).
                        code: MISS-INIT-CUST
                        resolution: Customer Resigns
                        nextStep: Upload a copy of the Customer Agreement with every initial box completed.
                        category: sibyl
                        documentType: customerAgreement
                        documentSlot: customerAgreement
                        pageRefs:
                          - 3
                        createdAt: "2026-11-02T17:31:10.000Z"
                        updatedAt: "2026-11-02T17:31:10.000Z"
                        resolvedAt: null
                        notes:
                          - text: We asked the customer to sign again. Expected on Friday.
                            by: Riley Rep
                            at: "2026-11-11T18:02:11.482Z"
                        history:
                          - kind: created
                            at: "2026-11-02T17:31:10.000Z"
                            by: SIBYL
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL, ACTOR_REQUIRED, INVALID_JSON, VALIDATION_FAILED, UNKNOWN_FIELD."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
                ACTOR_REQUIRED:
                  $ref: "#/components/examples/Error_ACTOR_REQUIRED"
                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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: PROJECT_CANCELLED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PROJECT_CANCELLED:
                  $ref: "#/components/examples/Error_PROJECT_CANCELLED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UNSUPPORTED_MEDIA_TYPE:
                  $ref: "#/components/examples/Error_UNSUPPORTED_MEDIA_TYPE"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - actions:write
      x-pe-scope: actions:write
      x-pe-rate-limit-bucket: write
      x-pe-actor: required
  /webhooks:
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Read the webhook URL
      description: |-
        Read the webhook URL of the key's environment. `url` is null when none is set.

        **Scope:** `webhooks:manage`. **X-PE-Actor-Email:** optional.

        **Errors:** the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      url: https://crm.installer.example/pe/webhooks
                      events:
                        - project.ic_approved
                        - project.pc_approved
                        - project.action_created
                      secretVersion: 1
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
    put:
      operationId: setWebhook
      tags:
        - Webhooks
      summary: Set the webhook URL
      description: |-
        Set the webhook URL of the key's environment. For a new subscription, the response has the `signingSecret`. Keep it: PE shows it only here and after a rotation. When you change an existing URL, the secret stays the same and `signingSecret` is null.

        **Scope:** `webhooks:manage`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`WEBHOOK_URL_INVALID`](#error-WEBHOOK_URL_INVALID), [`WEBHOOK_URL_NOT_HTTPS`](#error-WEBHOOK_URL_NOT_HTTPS), [`WEBHOOK_URL_PRIVATE_ADDRESS`](#error-WEBHOOK_URL_PRIVATE_ADDRESS).
      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:
              example:
                summary: Example
                value:
                  url: https://crm.installer.example/pe/webhooks
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookWithSecretResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      url: https://crm.installer.example/pe/webhooks
                      events:
                        - project.ic_approved
                        - project.pc_approved
                        - project.action_created
                      secretVersion: 1
                      signingSecret: whsec_exampleSecretValueShownOnce
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                WEBHOOK_URL_PRIVATE_ADDRESS:
                  $ref: "#/components/examples/Error_WEBHOOK_URL_PRIVATE_ADDRESS"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: write
      x-pe-actor: optional
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete the webhook URL
      description: |-
        Stop webhooks in the key's environment. A later `PUT /webhooks` starts a new subscription with a new secret, from that moment.

        **Scope:** `webhooks:manage`. **X-PE-Actor-Email:** optional.

        **Errors:** the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeletedResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      url: null
                      deleted: true
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: write
      x-pe-actor: optional
  /webhooks/rotate-secret:
    post:
      operationId: rotateWebhookSecret
      tags:
        - Webhooks
      summary: Rotate the signing secret
      description: |-
        Make a new signing secret. PE signs deliveries with the new secret from now on. Update your receiver at once.

        **Scope:** `webhooks:manage`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`WEBHOOK_NOT_CONFIGURED`](#error-WEBHOOK_NOT_CONFIGURED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookWithSecretResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      url: https://crm.installer.example/pe/webhooks
                      events:
                        - project.ic_approved
                        - project.pc_approved
                        - project.action_created
                      secretVersion: 2
                      signingSecret: whsec_exampleNewSecretValueShownOnce
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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_NOT_CONFIGURED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                WEBHOOK_NOT_CONFIGURED:
                  $ref: "#/components/examples/Error_WEBHOOK_NOT_CONFIGURED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: write
      x-pe-actor: optional
  /webhooks/test:
    post:
      operationId: testWebhook
      tags:
        - Webhooks
      summary: Send a test event
      description: |-
        Send a signed `webhook.test` event to your URL now and return the result. The call waits up to 5 seconds for your receiver.

        **Scope:** `webhooks:manage`. **X-PE-Actor-Email:** optional.

        **Errors** (and the common errors listed in Errors): [`WEBHOOK_NOT_CONFIGURED`](#error-WEBHOOK_NOT_CONFIGURED).
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookTestResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      eventId: evt_Tz8Kp3Lm6Qw9Rx2Vb5Nc7Df1
                      type: webhook.test
                      delivered: true
                      statusCode: 200
                      durationMs: 184
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SCOPE_NOT_GRANTED:
                  $ref: "#/components/examples/Error_SCOPE_NOT_GRANTED"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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_NOT_CONFIGURED."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                WEBHOOK_NOT_CONFIGURED:
                  $ref: "#/components/examples/Error_WEBHOOK_NOT_CONFIGURED"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - webhooks:manage
      x-pe-scope: webhooks:manage
      x-pe-rate-limit-bucket: write
      x-pe-actor: optional
  /sandbox/projects/{projectId}/simulate:
    post:
      operationId: simulateProjectEvent
      tags:
        - Sandbox
      summary: Simulate a PE event
      description: |-
        Apply one PE event to a Test project: approve or reject a document, raise an Action, approve the photos, approve IC or PC, or cancel the project. PE changes the project the same way a real review would. An IC or PC approval also sends the webhook event at the next check (within about 5 minutes). A new Action sends `project.action_created` within about 10 minutes. The `contract_*` events move the project's current Test contract instead and send `project.contract_status_changed`; the answer's `contract` shows it. Test keys only.

        **Scope:** `projects:read`. **X-PE-Actor-Email:** optional. **Test keys only.**

        **Errors** (and the common errors listed in Errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`SANDBOX_DOCUMENT_TYPE_UNKNOWN`](#error-SANDBOX_DOCUMENT_TYPE_UNKNOWN), [`SANDBOX_TRANSITION_INVALID`](#error-SANDBOX_TRANSITION_INVALID), [`PACKET_NOT_FOUND`](#error-PACKET_NOT_FOUND).
      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 (SBX-... in the Test environment).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SimulateRequest"
            examples:
              example:
                summary: Example
                value:
                  event: document_rejected
                  documentType: utilityBill
                  reason: The bill is older than 12 months. Upload a recent bill.
              contract:
                summary: A contract event
                value:
                  event: contract_declined
                  reason: The homeowner wants a smaller system.
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimulateResultResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      projectId: SBX-CA2611-SAND1
                      event: document_rejected
                      changed: true
                      status: Active
                      milestone: Project Onboarded
                      documentReviewStatus: Action Required (Installer)
                      approvals:
                        ic:
                          status: not_started
                          date: null
                        pc:
                          status: not_started
                          date: null
                      openActions: 1
                      actionId: act_Sb4Xk9Pq2Lm7
                      contract: null
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: test
                      timestamp: "2026-11-11T18: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"
          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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SCOPE_NOT_GRANTED, SANDBOX_ONLY."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                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: RESOURCE_NOT_FOUND, PACKET_NOT_FOUND."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                RESOURCE_NOT_FOUND:
                  $ref: "#/components/examples/Error_RESOURCE_NOT_FOUND"
                PACKET_NOT_FOUND:
                  $ref: "#/components/examples/Error_PACKET_NOT_FOUND"
        "409":
          description: "Conflict with the current state. Codes: SANDBOX_TRANSITION_INVALID."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SANDBOX_TRANSITION_INVALID:
                  $ref: "#/components/examples/Error_SANDBOX_TRANSITION_INVALID"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "415":
          description: "Unsupported media type. Codes: UNSUPPORTED_MEDIA_TYPE."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          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: SANDBOX_DOCUMENT_TYPE_UNKNOWN."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                SANDBOX_DOCUMENT_TYPE_UNKNOWN:
                  $ref: "#/components/examples/Error_SANDBOX_DOCUMENT_TYPE_UNKNOWN"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth:
            - projects:read
      x-pe-scope: projects:read
      x-pe-rate-limit-bucket: write
      x-pe-actor: optional
      x-pe-test-only: true
  /sandbox/scenarios:
    get:
      operationId: listSandboxScenarios
      tags:
        - Sandbox
      summary: List the Test upload scenarios
      description: |-
        List the contract upload scenarios of the Test environment, with the result of each. Test keys only.

        **Scope:** none. **X-PE-Actor-Email:** optional. **Test keys only.**

        **Errors:** the common errors listed in Errors.
      parameters:
        - $ref: "#/components/parameters/X-Request-Id"
        - $ref: "#/components/parameters/X-PE-Actor-Email"
      responses:
        "200":
          description: Success.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
            Cache-Control:
              $ref: "#/components/headers/Cache-Control"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScenarioListResponse"
              examples:
                example:
                  summary: Example
                  value:
                    data:
                      scenarios:
                        - scenario: project_created
                          default: true
                          description: The contract passes review and a sandbox project is created with no open Actions.
                          status: project_created
                          outcome: project_created
                          outcomeMessage: Participate Energy read the contract and created the project. Read it with GET /v2/installer/projects/{projectId} and follow its Actions and approvals.
                          createsProject: true
                          initialActions: 0
                        - scenario: project_created_action_required
                          default: false
                          description: The contract passes review and a sandbox project is created with two open Actions for the installer.
                          status: project_created
                          outcome: project_created
                          outcomeMessage: Participate Energy read the contract and created the project. Read it with GET /v2/installer/projects/{projectId} and follow its Actions and approvals.
                          createsProject: true
                          initialActions: 2
                    meta:
                      requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
                      environment: live
                      timestamp: "2026-11-11T18:02:11.482Z"
        "400":
          description: "The request is not valid. Codes: ACTOR_INVALID_EMAIL."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ACTOR_INVALID_EMAIL:
                  $ref: "#/components/examples/Error_ACTOR_INVALID_EMAIL"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: "Access is not allowed. Codes: INSTALLER_API_SUSPENDED, ENVIRONMENT_NOT_ENABLED, INSTALLER_NOT_ELIGIBLE, ACTOR_NOT_ON_ROSTER, SANDBOX_ONLY."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/X-Request-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                INSTALLER_API_SUSPENDED:
                  $ref: "#/components/examples/Error_INSTALLER_API_SUSPENDED"
                ENVIRONMENT_NOT_ENABLED:
                  $ref: "#/components/examples/Error_ENVIRONMENT_NOT_ENABLED"
                INSTALLER_NOT_ELIGIBLE:
                  $ref: "#/components/examples/Error_INSTALLER_NOT_ELIGIBLE"
                ACTOR_NOT_ON_ROSTER:
                  $ref: "#/components/examples/Error_ACTOR_NOT_ON_ROSTER"
                SANDBOX_ONLY:
                  $ref: "#/components/examples/Error_SANDBOX_ONLY"
        "413":
          $ref: "#/components/responses/BodyTooLarge"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          $ref: "#/components/responses/ServiceDisabled"
      security:
        - bearerAuth: []
      x-pe-scope: null
      x-pe-rate-limit-bucket: read
      x-pe-actor: optional
      x-pe-test-only: true
webhooks:
  project.ic_approved:
    post:
      operationId: webhookIcApproved
      summary: IC approved
      tags:
        - Webhooks
      description: PE approved Inspection Complete on one of your projects. Verify PE-Signature before you trust the body.
      security: []
      parameters:
        - $ref: "#/components/parameters/PE-Event-Id"
        - $ref: "#/components/parameters/PE-Event-Type"
        - $ref: "#/components/parameters/PE-Signature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApprovalEvent"
            examples:
              example:
                summary: IC approved
                value:
                  id: evt_3f9a1c2b7d4e5f60718293a4
                  type: project.ic_approved
                  createdAt: "2026-11-11T18:05:00.000Z"
                  environment: live
                  data:
                    projectId: CA2611-SMIT1
                    externalId: crm-10442
                    approval:
                      stage: ic
                      approvedAt: "2026-11-11"
      responses:
        "200":
          description: Any 2xx status within 10 seconds means delivered. PE retries any other answer.
  project.pc_approved:
    post:
      operationId: webhookPcApproved
      summary: PC approved
      tags:
        - Webhooks
      description: PE approved Project Complete on one of your projects. Verify PE-Signature before you trust the body.
      security: []
      parameters:
        - $ref: "#/components/parameters/PE-Event-Id"
        - $ref: "#/components/parameters/PE-Event-Type"
        - $ref: "#/components/parameters/PE-Signature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApprovalEvent"
            examples:
              example:
                summary: PC approved
                value:
                  id: evt_8c1d2e3f4a5b6c7d8e9f0a1b
                  type: project.pc_approved
                  createdAt: "2026-12-18T17:00:00.000Z"
                  environment: live
                  data:
                    projectId: CA2611-SMIT1
                    externalId: crm-10442
                    approval:
                      stage: pc
                      approvedAt: "2026-12-18"
      responses:
        "200":
          description: Any 2xx status within 10 seconds means delivered. PE retries any other answer.
  project.action_created:
    post:
      operationId: webhookActionCreated
      summary: Action created
      tags:
        - Webhooks
      description: PE created an Action on one of your projects. `data.action` is the same object that GET /projects/{projectId}/actions returns for one Action. Verify PE-Signature before you trust the body.
      security: []
      parameters:
        - $ref: "#/components/parameters/PE-Event-Id"
        - $ref: "#/components/parameters/PE-Event-Type"
        - $ref: "#/components/parameters/PE-Signature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionCreatedEvent"
            examples:
              example:
                summary: Action created
                value:
                  id: evt_5b2c9d0e1f3a4b6c7d8e9f01
                  type: project.action_created
                  createdAt: "2026-11-02T17:35:00.000Z"
                  environment: live
                  data:
                    projectId: CA2611-SMIT1
                    externalId: crm-10442
                    action:
                      actionId: act_7Gm2Qp9xVb4
                      status: open
                      severity: fail
                      title: MISS-INIT-CUST
                      description: The customer initials are missing on page 3 of the Customer Agreement (Section 9, Arbitration).
                      code: MISS-INIT-CUST
                      resolution: Customer Resigns
                      nextStep: Upload a copy of the Customer Agreement with every initial box completed.
                      category: sibyl
                      documentType: customerAgreement
                      documentSlot: customerAgreement
                      pageRefs:
                        - 3
                      createdAt: "2026-11-02T17:31:10.000Z"
                      updatedAt: "2026-11-02T17:31:10.000Z"
                      resolvedAt: null
                      notes: []
                      history:
                        - kind: created
                          at: "2026-11-02T17:31:10.000Z"
                          by: SIBYL
      responses:
        "200":
          description: Any 2xx status within 10 seconds means delivered. PE retries any other answer.
  webhook.test:
    post:
      operationId: webhookTest
      summary: Test event
      tags:
        - Webhooks
      description: Sent by POST /webhooks/test.
      security: []
      parameters:
        - $ref: "#/components/parameters/PE-Event-Id"
        - $ref: "#/components/parameters/PE-Event-Type"
        - $ref: "#/components/parameters/PE-Signature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TestEvent"
            examples:
              example:
                summary: Test event
                value:
                  id: evt_Tz8Kp3Lm6Qw9Rx2Vb5Nc7Df1
                  type: webhook.test
                  createdAt: "2026-11-11T18:02:11.000Z"
                  environment: test
                  data: {}
      responses:
        "200":
          description: Any 2xx status within 10 seconds means delivered. PE retries any other answer.
  project.contract_status_changed:
    post:
      operationId: webhookContractStatusChanged
      summary: Contract status changed
      tags:
        - Webhooks
      description: "The contract of one of your projects changed: it was sent, viewed, signed by a signer, completed, declined, voided, expired or cancelled. One event for each new state. Read GET /projects/{projectId}/contract-esign for the names and emails. Verify PE-Signature before you trust the body."
      security: []
      parameters:
        - $ref: "#/components/parameters/PE-Event-Id"
        - $ref: "#/components/parameters/PE-Event-Type"
        - $ref: "#/components/parameters/PE-Signature"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractStatusChangedEvent"
            examples:
              example:
                summary: Contract completed
                value:
                  id: evt_8c1d2e3f4a5b6c7d8e9f0a1b
                  type: project.contract_status_changed
                  createdAt: "2026-11-12T19:05:00.000Z"
                  environment: live
                  data:
                    projectId: CA2611-EXAM1
                    externalId: crm-10442
                    packetId: pkt4Hn8Qa2Zt6WcYb1Lm
                    status: completed
                    signers:
                      - role: customer
                        status: signed
                        signedAt: "2026-11-12T19:01:44.000Z"
                      - role: installer
                        status: signed
                        signedAt: "2026-11-12T18:02:12.000Z"
                    occurredAt: "2026-11-12T19:01:44.000Z"
      responses:
        "200":
          description: Any 2xx status within 10 seconds means delivered. PE retries any other answer.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ik_test_... or ik_live_...
      description: "Your Installer API key: ik_test_ (Test) or ik_live_ (production) and 40 letters and digits. Send it as Authorization: Bearer <key>. Keep it on your servers. The security requirement of each operation lists the scope it needs."
  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 no-store.
      schema:
        type: string
        const: no-store
    Retry-After:
      description: Seconds to wait before you retry.
      schema:
        type: integer
    X-RateLimit-Limit:
      description: The per-minute limit of the bucket of this endpoint.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Calls left in the current minute.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: When the current minute ends, in Unix seconds.
      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: crm-7f3c2b91
    X-PE-Actor-Email:
      name: X-PE-Actor-Email
      in: header
      required: false
      description: The email of the person who does the work. Optional here. When you send it, PE checks it against your company's users and allowed domains.
      schema:
        type: string
        format: email
        maxLength: 254
      example: riley@installer.example
    X-PE-Actor-Email-Required:
      name: X-PE-Actor-Email
      in: header
      required: true
      description: The email of the person who does the work. Required here. It must be an active user of your company, or use one of your allowed domains.
      schema:
        type: string
        format: email
        maxLength: 254
      example: riley@installer.example
    PE-Event-Id:
      name: PE-Event-Id
      in: header
      required: true
      description: The event id (evt_...). The same on every retry. Use it to ignore repeats.
      schema:
        type: string
    PE-Event-Type:
      name: PE-Event-Type
      in: header
      required: true
      description: The event type.
      schema:
        $ref: "#/components/schemas/WebhookEventType"
    PE-Signature:
      name: PE-Signature
      in: header
      required: true
      description: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your signing secret>. Reject a t more than 300 seconds from your clock.
      schema:
        type: string
        pattern: ^t=\d+,v1=[0-9a-f]{64}$
  responses:
    Unauthorized:
      description: "Authentication failed. Codes: AUTH_HEADER_MISSING, AUTH_HEADER_MALFORMED, KEY_IS_V1, KEY_IS_DESIGN_API, KEY_INVALID, KEY_REVOKED, KEY_EXPIRED."
      headers:
        X-Request-Id:
          $ref: "#/components/headers/X-Request-Id"
      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"
            KEY_IS_V1:
              $ref: "#/components/examples/Error_KEY_IS_V1"
            KEY_IS_DESIGN_API:
              $ref: "#/components/examples/Error_KEY_IS_DESIGN_API"
            KEY_INVALID:
              $ref: "#/components/examples/Error_KEY_INVALID"
            KEY_REVOKED:
              $ref: "#/components/examples/Error_KEY_REVOKED"
            KEY_EXPIRED:
              $ref: "#/components/examples/Error_KEY_EXPIRED"
    BodyTooLarge:
      description: "Too large. Codes: BODY_TOO_LARGE."
      headers:
        X-Request-Id:
          $ref: "#/components/headers/X-Request-Id"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            BODY_TOO_LARGE:
              $ref: "#/components/examples/Error_BODY_TOO_LARGE"
    RateLimited:
      description: "A limit was reached. Codes: RATE_LIMITED."
      headers:
        X-Request-Id:
          $ref: "#/components/headers/X-Request-Id"
        Retry-After:
          $ref: "#/components/headers/Retry-After"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            RATE_LIMITED:
              $ref: "#/components/examples/Error_RATE_LIMITED"
    InternalError:
      description: "Unexpected error. Codes: INTERNAL_ERROR."
      headers:
        X-Request-Id:
          $ref: "#/components/headers/X-Request-Id"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            INTERNAL_ERROR:
              $ref: "#/components/examples/Error_INTERNAL_ERROR"
    ServiceDisabled:
      description: "A service is unavailable. Codes: SERVICE_DISABLED."
      headers:
        X-Request-Id:
          $ref: "#/components/headers/X-Request-Id"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            SERVICE_DISABLED:
              $ref: "#/components/examples/Error_SERVICE_DISABLED"
  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 <key>\" with your Installer API key. Keys start with ik_test_ or ik_live_."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-AUTH_HEADER_MISSING
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_AUTH_HEADER_MALFORMED:
      summary: AUTH_HEADER_MALFORMED
      value:
        error:
          code: AUTH_HEADER_MALFORMED
          message: "The Authorization header does not hold an Installer API key. Send \"Authorization: Bearer <key>\", where the key starts with ik_test_ or ik_live_ followed by 40 letters and digits, with no spaces or line breaks."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-AUTH_HEADER_MALFORMED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_KEY_IS_V1:
      summary: KEY_IS_V1
      value:
        error:
          code: KEY_IS_V1
          message: This is an Installer API v1 key (it starts with pk_). v1 keys work only at https://api.participate.energy/v1. Use an Installer API v2 key (ik_test_ or ik_live_) here, or ask Participate Energy for one at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-KEY_IS_V1
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_KEY_IS_DESIGN_API:
      summary: KEY_IS_DESIGN_API
      value:
        error:
          code: KEY_IS_DESIGN_API
          message: This is a Design API credential or access token. Design API credentials work only at https://api.participate.energy/v2/design. The Installer API v2 takes an installer key that starts with ik_test_ or ik_live_.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-KEY_IS_DESIGN_API
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_KEY_INVALID:
      summary: KEY_INVALID
      value:
        error:
          code: KEY_INVALID
          message: The key is not recognized. Check that the full key was copied without spaces, or ask Participate Energy for a new key at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-KEY_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_KEY_REVOKED:
      summary: KEY_REVOKED
      value:
        error:
          code: KEY_REVOKED
          message: The key ik_live_Xy7pQ2 was revoked. Use another active key, or ask Participate Energy for a new one at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-KEY_REVOKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_KEY_EXPIRED:
      summary: KEY_EXPIRED
      value:
        error:
          code: KEY_EXPIRED
          message: The key ik_live_Xy7pQ2 expired at 2026-11-01T00:00:00.000Z. Keys last 12 months; ask Participate Energy for a new key at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-KEY_EXPIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: null
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_INSTALLER_API_SUSPENDED:
      summary: INSTALLER_API_SUSPENDED
      value:
        error:
          code: INSTALLER_API_SUSPENDED
          message: Installer API access for your company is suspended. Contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-INSTALLER_API_SUSPENDED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 key for an enabled environment, or ask Participate Energy to enable it.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ENVIRONMENT_NOT_ENABLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_INSTALLER_NOT_ELIGIBLE:
      summary: INSTALLER_NOT_ELIGIBLE
      value:
        error:
          code: INSTALLER_NOT_ELIGIBLE
          message: Your organization is not set up as a Participate Energy install partner, so this key cannot be used. Contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-INSTALLER_NOT_ELIGIBLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SANDBOX_ONLY:
      summary: SANDBOX_ONLY
      value:
        error:
          code: SANDBOX_ONLY
          message: This endpoint works only with Test keys (ik_test_). Send the request with your Test key.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SANDBOX_ONLY
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SCOPE_NOT_GRANTED:
      summary: SCOPE_NOT_GRANTED
      value:
        error:
          code: SCOPE_NOT_GRANTED
          message: "This endpoint needs the scope projects:write, and your key does not carry it. The key carries: avl:read, projects:read. Ask Participate Energy for a key with the scope you need."
          retryable: false
          details:
            - field: ""
              issue: The key does not carry this scope.
              expected: projects:write
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SCOPE_NOT_GRANTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_ACTOR_NOT_ON_ROSTER:
      summary: ACTOR_NOT_ON_ROSTER
      value:
        error:
          code: ACTOR_NOT_ON_ROSTER
          message: The X-PE-Actor-Email address is not an active Raceway user of your company, and its domain is not one of your allowed domains. Send the email of the person doing the work as Raceway knows it, or add the user in Raceway first.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ACTOR_NOT_ON_ROSTER
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 key in the live environment. Check the id, and use a key for the environment where the project was created.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-RESOURCE_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EXTERNAL_ID_AMBIGUOUS:
      summary: EXTERNAL_ID_AMBIGUOUS
      value:
        error:
          code: EXTERNAL_ID_AMBIGUOUS
          message: More than one of your projects uses the externalId crm-10442. Read the project by its projectId instead; the projectIds are in details.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EXTERNAL_ID_AMBIGUOUS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_BODY_TOO_LARGE:
      summary: BODY_TOO_LARGE
      value:
        error:
          code: BODY_TOO_LARGE
          message: The request body is 2097152 bytes, more than the 1048576 bytes allowed. Send a smaller JSON body.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-BODY_TOO_LARGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-UNSUPPORTED_MEDIA_TYPE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-INVALID_JSON
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_VALIDATION_FAILED:
      summary: VALIDATION_FAILED
      value:
        error:
          code: VALIDATION_FAILED
          message: The request did not pass validation (1 problem(s)). Fix the fields listed in details and send the request again.
          retryable: false
          details:
            - field: customer.email
              issue: Invalid email address
              expected: an email address
              received: string
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-VALIDATION_FAILED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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: customerName. Allowed fields: stateCode, productType, externalId, salesRep, fileName, sandboxScenario. Remove the other fields and send the request again."
          retryable: false
          details:
            - field: customerName
              issue: This field is not accepted.
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UNKNOWN_FIELD
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_CURSOR_INVALID:
      summary: CURSOR_INVALID
      value:
        error:
          code: CURSOR_INVALID
          message: The cursor is not valid for this list. Send the nextCursor from the previous page of the same request without changes, or leave cursor out to start at the first page.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CURSOR_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_ACTOR_REQUIRED:
      summary: ACTOR_REQUIRED
      value:
        error:
          code: ACTOR_REQUIRED
          message: This endpoint needs the X-PE-Actor-Email header. Send the email of the person doing the work (for example your sales rep) as Raceway knows it.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ACTOR_REQUIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_ACTOR_INVALID_EMAIL:
      summary: ACTOR_INVALID_EMAIL
      value:
        error:
          code: ACTOR_INVALID_EMAIL
          message: The X-PE-Actor-Email header is not a valid email address. Send one email address, for example rep@installer.example.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ACTOR_INVALID_EMAIL
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_RATE_LIMITED:
      summary: RATE_LIMITED
      value:
        error:
          code: RATE_LIMITED
          message: "Too many requests: the limit is 120 per minute. Wait for the Retry-After seconds, then retry."
          retryable: true
          details:
            - field: ""
              issue: Rate limit reached.
              limit: 120
              window: minute
              resetAt: "2026-11-11T18:03:00.000Z"
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-RATE_LIMITED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_DAILY_QUOTA_EXCEEDED:
      summary: DAILY_QUOTA_EXCEEDED
      value:
        error:
          code: DAILY_QUOTA_EXCEEDED
          message: Your company used its daily limit of 120 contract uploads in the live environment. The limit resets at 2026-11-12T00:00:00.000Z; retry after that.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DAILY_QUOTA_EXCEEDED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_NOT_YET_AVAILABLE:
      summary: NOT_YET_AVAILABLE
      value:
        error:
          code: NOT_YET_AVAILABLE
          message: This feature is not available in the Installer API yet. See https://api.participate.energy/docs/installer/v2/ for the endpoints that work today.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-NOT_YET_AVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_UPSTREAM_TIMEOUT:
      summary: UPSTREAM_TIMEOUT
      value:
        error:
          code: UPSTREAM_TIMEOUT
          message: A service this request depends on did not answer in time. Retry the same request in a few minutes.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UPSTREAM_TIMEOUT
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SERVICE_DISABLED:
      summary: SERVICE_DISABLED
      value:
        error:
          code: SERVICE_DISABLED
          message: The Installer API is turned off for now by Participate Energy. Retry later, or ask raceway.support@participate.energy for the status.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SERVICE_DISABLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 after waits of 1, 2, 4, 8 and 16 seconds, and stop after 5 tries. If it still fails, send the request id to raceway.support@participate.energy.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-INTERNAL_ERROR
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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, Sacramento, CA 95814, USA
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ADDRESS_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-ADDRESS_OUTSIDE_US
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_STATE_NOT_SUPPORTED:
      summary: STATE_NOT_SUPPORTED
      value:
        error:
          code: STATE_NOT_SUPPORTED
          message: Participate Energy does not operate in NV. Use a state from GET /v2/installer/states.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-STATE_NOT_SUPPORTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_STATE_MISMATCH:
      summary: STATE_MISMATCH
      value:
        error:
          code: STATE_MISMATCH
          message: The site address or its ZIP code is in CA, but the request says NV. Send the stateCode and zipCode of the site address.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-STATE_MISMATCH
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/states, or request the state in the Installer Portal.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-STATE_NOT_ACTIVE_FOR_INSTALLER
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PRODUCT_NOT_ENABLED:
      summary: PRODUCT_NOT_ENABLED
      value:
        error:
          code: PRODUCT_NOT_ENABLED
          message: The product Distributed Microgrid is not enabled for this installer. Contact Participate Energy to turn it on.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PRODUCT_NOT_ENABLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SAFE_HARBOR_OPPORTUNITY_NOT_FOUND:
      summary: SAFE_HARBOR_OPPORTUNITY_NOT_FOUND
      value:
        error:
          code: SAFE_HARBOR_OPPORTUNITY_NOT_FOUND
          message: No Safe Harbor opportunity SHO-0042 belongs to this installer. Use an opportunityId from GET /v2/installer/safe-harbor/opportunities.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EQUIPMENT_NOT_ON_AVL:
      summary: EQUIPMENT_NOT_ON_AVL
      value:
        error:
          code: EQUIPMENT_NOT_ON_AVL
          message: The equipment QCELL-999 is not on the Participate Energy approved vendor list. Use a SKU from GET /v2/installer/avl.
          retryable: false
          details:
            - field: items[0].name
              issue: No AVL item matches this name.
              suggestions:
                - avlItemId: avl_8Hc2Kd91LmQ4
                  name: Qcells - Q.TRON BLK M-G2+ 430
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_NOT_ON_AVL
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EQUIPMENT_AMBIGUOUS:
      summary: EQUIPMENT_AMBIGUOUS
      value:
        error:
          code: EQUIPMENT_AMBIGUOUS
          message: The equipment QCELL-999 matches more than one item on the approved vendor list. Send the exact SKU from GET /v2/installer/avl.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_AMBIGUOUS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-SALES_TAX_UNRESOLVED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 where the endpoint allows it.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EC_LOOKUP_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-TAX_RATE_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-ADDRESS_LOOKUP_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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; 3000000 is outside that range. It looks like an amount in cents; send US dollars, for example 60000 for $60,000.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EPC_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_NET_AMOUNT_DUE_OUT_OF_RANGE:
      summary: NET_AMOUNT_DUE_OUT_OF_RANGE
      value:
        error:
          code: NET_AMOUNT_DUE_OUT_OF_RANGE
          message: "The targetNetAmountDue 1000 cannot be priced: the EPC that gives it must be from 1,000 to 500,000 USD. Check the amount and the other inputs."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-NET_AMOUNT_DUE_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_ROOFING_COST_INVALID:
      summary: ROOFING_COST_INVALID
      value:
        error:
          code: ROOFING_COST_INVALID
          message: "The roofing costs are not valid: ineligibleRoofingCost is negative. Send amounts of 0 or more, in USD."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ROOFING_COST_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 (5000) are not valid for this opportunity (1880 available). Send a whole number from 1 to the available units.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SAFE_HARBOR_UNITS_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_INCENTIVE_NOT_AVAILABLE:
      summary: INCENTIVE_NOT_AVAILABLE
      value:
        error:
          code: INCENTIVE_NOT_AVAILABLE
          message: "The incentive hawaii_retitc is not available: it is not an included incentive for this installer or state. Send type \"none\", or an incentive that applies."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-INCENTIVE_NOT_AVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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. Contact Participate Energy to enroll.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SUNGAGE_NOT_ENROLLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 in the X-PE-Actor-Email header, or register the user with Sungage.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SUNGAGE_USER_NOT_REGISTERED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/pricing/sungage/products.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SUNGAGE_PRODUCT_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-SUNGAGE_UNAVAILABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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. Contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-INSTALLER_ON_HOLD
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PRODUCT_NOT_AVAILABLE_IN_STATE:
      summary: PRODUCT_NOT_AVAILABLE_IN_STATE
      value:
        error:
          code: PRODUCT_NOT_AVAILABLE_IN_STATE
          message: The product Distributed Microgrid is not available in NV. Send a stateCode where Participate Energy offers the product, or contact raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PRODUCT_NOT_AVAILABLE_IN_STATE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PRODUCT_NOT_SUPPORTED_BY_API:
      summary: PRODUCT_NOT_SUPPORTED_BY_API
      value:
        error:
          code: PRODUCT_NOT_SUPPORTED_BY_API
          message: Contract uploads through the API support Synthetic Cash only. Upload Distributed Microgrid contracts in the Installer Portal.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PRODUCT_NOT_SUPPORTED_BY_API
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EXTERNAL_ID_IN_USE:
      summary: EXTERNAL_ID_IN_USE
      value:
        error:
          code: EXTERNAL_ID_IN_USE
          message: The externalId crm-10442 is already used by this installer. a value is negative To create another project, send a different externalId.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EXTERNAL_ID_IN_USE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 with a test key. Remove it from requests made with a live key.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SANDBOX_FIELD_IN_LIVE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_UPLOAD_ALREADY_SUBMITTED:
      summary: UPLOAD_ALREADY_SUBMITTED
      value:
        error:
          code: UPLOAD_ALREADY_SUBMITTED
          message: Upload iup_9Bv4Nc7Xz2Lk5Hj8Gf3D was already submitted and is now queued. Poll GET /v2/installer/contract-uploads/iup_9Bv4Nc7Xz2Lk5Hj8Gf3D for the result instead of submitting again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UPLOAD_ALREADY_SUBMITTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_UPLOAD_URL_EXPIRED:
      summary: UPLOAD_URL_EXPIRED
      value:
        error:
          code: UPLOAD_URL_EXPIRED
          message: The upload URL for upload iup_9Bv4Nc7Xz2Lk5Hj8Gf3D expired before a file arrived. Create a new upload with POST /v2/installer/contract-uploads; you can use the same externalId.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UPLOAD_URL_EXPIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_UPLOAD_FILE_MISSING:
      summary: UPLOAD_FILE_MISSING
      value:
        error:
          code: UPLOAD_FILE_MISSING
          message: No file was found for upload iup_9Bv4Nc7Xz2Lk5Hj8Gf3D. PUT the PDF to the uploadUrl with the uploadHeaders first, then submit.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UPLOAD_FILE_MISSING
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 externalId.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UPLOAD_FILE_TOO_LARGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_UPLOAD_NOT_PDF:
      summary: UPLOAD_NOT_PDF
      value:
        error:
          code: UPLOAD_NOT_PDF
          message: The file for upload iup_9Bv4Nc7Xz2Lk5Hj8Gf3D is not a PDF. Create a new upload and PUT the signed customer agreement as a PDF; you can use the same externalId.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UPLOAD_NOT_PDF
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PROJECT_CANCELLED:
      summary: PROJECT_CANCELLED
      value:
        error:
          code: PROJECT_CANCELLED
          message: Project CA2611-SMIT1 was cancelled, so it cannot be changed. You can still read it. If this is a mistake, contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PROJECT_CANCELLED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PROJECT_LOCKED:
      summary: PROJECT_LOCKED
      value:
        error:
          code: PROJECT_LOCKED
          message: Project CA2611-SMIT1 cannot be edited at the Project Complete milestone. This project is complete and cannot be edited. If a value must change, contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PROJECT_LOCKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_CHANGE_ORDER_REQUIRED:
      summary: CHANGE_ORDER_REQUIRED
      value:
        error:
          code: CHANGE_ORDER_REQUIRED
          message: "Project CA2611-SMIT1 passed IC approval, so its equipment can no longer be changed through the API. A change now needs a signed change order: upload it as the project's change order document, or contact Participate Energy at raceway.support@participate.energy."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CHANGE_ORDER_REQUIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_CHANGE_ORDER_BLOCKED:
      summary: CHANGE_ORDER_BLOCKED
      value:
        error:
          code: CHANGE_ORDER_BLOCKED
          message: This change to project CA2611-SMIT1 needs Participate Energy review and cannot be made through the API. Contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CHANGE_ORDER_BLOCKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PROJECT_CHANGED_SINCE_READ:
      summary: PROJECT_CHANGED_SINCE_READ
      value:
        error:
          code: PROJECT_CHANGED_SINCE_READ
          message: Project CA2611-SMIT1 changed after you read it. Your expectedUpdatedAt is 2026-11-09T10:00:00.000Z but the project's updatedAt is 2026-11-10T21:14:55.000Z. Read the project again, then resend the change.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PROJECT_CHANGED_SINCE_READ
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EXTERNAL_ID_TAKEN:
      summary: EXTERNAL_ID_TAKEN
      value:
        error:
          code: EXTERNAL_ID_TAKEN
          message: This externalId is already used by project CA2610-JONE2 of your company. Each project needs its own externalId. Send a different one.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EXTERNAL_ID_TAKEN
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FIELD_NOT_EDITABLE:
      summary: FIELD_NOT_EDITABLE
      value:
        error:
          code: FIELD_NOT_EDITABLE
          message: "\"sandboxScenario\" cannot be set through the API. unknown Remove the field and send the request again."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FIELD_NOT_EDITABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_UTILITY_NOT_RECOGNIZED:
      summary: UTILITY_NOT_RECOGNIZED
      value:
        error:
          code: UTILITY_NOT_RECOGNIZED
          message: The utility name is not in the Participate Energy utility list. Use a name from GET /utilities, sending the zipCode of the project site, and send the change again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UTILITY_NOT_RECOGNIZED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PROJECT_UPDATE_REJECTED:
      summary: PROJECT_UPDATE_REJECTED
      value:
        error:
          code: PROJECT_UPDATE_REJECTED
          message: Participate Energy could not save the change because 1 value(s) failed validation. See details, fix the values and send the change again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PROJECT_UPDATE_REJECTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FINANCIALS_SET_BY_PE:
      summary: FINANCIALS_SET_BY_PE
      value:
        error:
          code: FINANCIALS_SET_BY_PE
          message: Financials on Distributed Microgrid projects are set by PE. Contact PE to change them.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FINANCIALS_SET_BY_PE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FINANCIALS_INVALID:
      summary: FINANCIALS_INVALID
      value:
        error:
          code: FINANCIALS_INVALID
          message: The financials for project CA2611-SMIT1 cannot be computed from these inputs. See details, fix the inputs and send them again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FINANCIALS_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FINANCIALS_EQUIPMENT_UNRESOLVED:
      summary: FINANCIALS_EQUIPMENT_UNRESOLVED
      value:
        error:
          code: FINANCIALS_EQUIPMENT_UNRESOLVED
          message: Project CA2611-SMIT1 has equipment that is not matched to the approved vendor list yet, so its lease factor is not final. Fix the equipment first with PUT /projects/CA2611-SMIT1/equipment, then update the financials.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FINANCIALS_EQUIPMENT_UNRESOLVED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EQUIPMENT_WRONG_CATEGORY:
      summary: EQUIPMENT_WRONG_CATEGORY
      value:
        error:
          code: EQUIPMENT_WRONG_CATEGORY
          message: "Equipment items that point to an approved vendor list item of another category: 1. See details, then send each item under its own category."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_WRONG_CATEGORY
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EQUIPMENT_INVALID:
      summary: EQUIPMENT_INVALID
      value:
        error:
          code: EQUIPMENT_INVALID
          message: The equipment change was not accepted (1 problem(s)). See details, fix the items and send the change again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EQUIPMENT_DOCUMENTS_SIGNED:
      summary: EQUIPMENT_DOCUMENTS_SIGNED
      value:
        error:
          code: EQUIPMENT_DOCUMENTS_SIGNED
          message: Project CA2611-SMIT1 has 1 signed document(s) that list its current equipment, such as a Bill of Sale. Changing the equipment voids them, which needs a confirmation in the Installer Portal. Make this equipment change in the portal, or contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_DOCUMENTS_SIGNED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SAFE_HARBOR_WRONG_INSTALLER:
      summary: SAFE_HARBOR_WRONG_INSTALLER
      value:
        error:
          code: SAFE_HARBOR_WRONG_INSTALLER
          message: Safe Harbor opportunity SHO-0042 belongs to another company in your organization. Pick an opportunity that belongs to the installer of project CA2611-SMIT1.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SAFE_HARBOR_WRONG_INSTALLER
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SAFE_HARBOR_NOT_FOR_DM:
      summary: SAFE_HARBOR_NOT_FOR_DM
      value:
        error:
          code: SAFE_HARBOR_NOT_FOR_DM
          message: Safe Harbor does not apply to Distributed Microgrid projects. Contact PE if this project needs a Safe Harbor opportunity.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SAFE_HARBOR_NOT_FOR_DM
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SAFE_HARBOR_OPPORTUNITY_CLOSED:
      summary: SAFE_HARBOR_OPPORTUNITY_CLOSED
      value:
        error:
          code: SAFE_HARBOR_OPPORTUNITY_CLOSED
          message: Safe Harbor opportunity SHO-0042 is queued and can no longer be linked. Pick an opportunity that is still open.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SAFE_HARBOR_OPPORTUNITY_CLOSED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SAFE_HARBOR_NO_UNITS:
      summary: SAFE_HARBOR_NO_UNITS
      value:
        error:
          code: SAFE_HARBOR_NO_UNITS
          message: Safe Harbor opportunity SHO-0042 has no units left. Pick another opportunity, or contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SAFE_HARBOR_NO_UNITS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SAFE_HARBOR_NOT_APPLICABLE:
      summary: SAFE_HARBOR_NOT_APPLICABLE
      value:
        error:
          code: SAFE_HARBOR_NOT_APPLICABLE
          message: "Safe Harbor opportunity SHO-0042 cannot be linked to project CA2611-SMIT1: the project does not meet the opportunity's rules (for example, its equipment is not on the opportunity's custom AVL). Check the equipment, or contact Participate Energy at raceway.support@participate.energy."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SAFE_HARBOR_NOT_APPLICABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SAFE_HARBOR_CONSUMED:
      summary: SAFE_HARBOR_CONSUMED
      value:
        error:
          code: SAFE_HARBOR_CONSUMED
          message: Project CA2611-SMIT1 already used Safe Harbor units, so its opportunity cannot be unlinked through the API. Contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SAFE_HARBOR_CONSUMED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_DOCUMENT_TYPE_NOT_UPLOADABLE:
      summary: DOCUMENT_TYPE_NOT_UPLOADABLE
      value:
        error:
          code: DOCUMENT_TYPE_NOT_UPLOADABLE
          message: The document type signedFinalPermit is not one you can upload on project CA2611-SMIT1. GET /v2/installer/projects/CA2611-SMIT1/documents lists the document types you can upload.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DOCUMENT_TYPE_NOT_UPLOADABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PHOTOS_USE_PHOTO_UPLOAD:
      summary: PHOTOS_USE_PHOTO_UPLOAD
      value:
        error:
          code: PHOTOS_USE_PHOTO_UPLOAD
          message: Photos are not uploaded as a document. Use POST /v2/installer/projects/CA2611-SMIT1/photos/roof_top/uploads with the photo category instead.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PHOTOS_USE_PHOTO_UPLOAD
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_DOCUMENT_UPLOAD_CLOSED:
      summary: DOCUMENT_UPLOAD_CLOSED
      value:
        error:
          code: DOCUMENT_UPLOAD_CLOSED
          message: "Uploads of signedFinalPermit are closed on project CA2611-SMIT1: This document locked when the project was approved at IC. Ask Participate Energy if a file still needs to change."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DOCUMENT_UPLOAD_CLOSED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_DOCUMENT_LOCKED:
      summary: DOCUMENT_LOCKED
      value:
        error:
          code: DOCUMENT_LOCKED
          message: This document cannot change right now. Participate Energy is processing this document. Ask Participate Energy if it must change.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DOCUMENT_LOCKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_CONTENT_TYPE_NOT_ALLOWED:
      summary: CONTENT_TYPE_NOT_ALLOWED
      value:
        error:
          code: CONTENT_TYPE_NOT_ALLOWED
          message: "This content type is not accepted for a document. Send one of: application/pdf, image/jpeg, image/png, image/heic, image/heif."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CONTENT_TYPE_NOT_ALLOWED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FILE_NOT_RECEIVED:
      summary: FILE_NOT_RECEIVED
      value:
        error:
          code: FILE_NOT_RECEIVED
          message: No file has arrived for upload ifu_Q8w2Er5Ty7Ui9Op1As3D yet. PUT the file to uploadUrl with the uploadHeaders, then confirm again.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FILE_NOT_RECEIVED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FILE_UPLOAD_EXPIRED:
      summary: FILE_UPLOAD_EXPIRED
      value:
        error:
          code: FILE_UPLOAD_EXPIRED
          message: The upload URL for ifu_Q8w2Er5Ty7Ui9Op1As3D expired before the file arrived. Create a new upload and send the file within 15 minutes.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FILE_UPLOAD_EXPIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FILE_UPLOAD_IN_PROGRESS:
      summary: FILE_UPLOAD_IN_PROGRESS
      value:
        error:
          code: FILE_UPLOAD_IN_PROGRESS
          message: Upload ifu_Q8w2Er5Ty7Ui9Op1As3D is being confirmed by another request. Wait a few seconds, then confirm again to read the result.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FILE_UPLOAD_IN_PROGRESS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FILE_TOO_LARGE:
      summary: FILE_TOO_LARGE
      value:
        error:
          code: FILE_TOO_LARGE
          message: The file uploaded for ifu_Q8w2Er5Ty7Ui9Op1As3D is 62914560 bytes, more than the 52428800 bytes allowed. Create a new upload with a smaller file.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FILE_TOO_LARGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FILE_CONTENT_MISMATCH:
      summary: FILE_CONTENT_MISMATCH
      value:
        error:
          code: FILE_CONTENT_MISMATCH
          message: "The file uploaded for ifu_Q8w2Er5Ty7Ui9Op1As3D is not a valid application/pdf file: its first bytes look like image/png, not the content type you declared. Create a new upload with the correct contentType and file."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FILE_CONTENT_MISMATCH
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_DOCUMENT_ARCHIVE_BLOCKED:
      summary: DOCUMENT_ARCHIVE_BLOCKED
      value:
        error:
          code: DOCUMENT_ARCHIVE_BLOCKED
          message: Version 1 of signedFinalPermit cannot be archived or restored. This file can no longer be changed. GET /v2/installer/projects/CA2611-SMIT1/documents shows each version and its state.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DOCUMENT_ARCHIVE_BLOCKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_PHOTO_CATEGORY_UNKNOWN:
      summary: PHOTO_CATEGORY_UNKNOWN
      value:
        error:
          code: PHOTO_CATEGORY_UNKNOWN
          message: The photo category roof_top does not exist. GET /v2/installer/projects/CA2611-SMIT1/photos lists the categories for this project.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PHOTO_CATEGORY_UNKNOWN
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_MONITORING_ACCESS_INVALID:
      summary: MONITORING_ACCESS_INVALID
      value:
        error:
          code: MONITORING_ACCESS_INVALID
          message: "The monitoring sites are not valid: Enter the Enphase system ID. It contains numbers only. Fix the sites listed in details and send the request again."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-MONITORING_ACCESS_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_MONITORING_SITE_DUPLICATE:
      summary: MONITORING_SITE_DUPLICATE
      value:
        error:
          code: MONITORING_SITE_DUPLICATE
          message: "A monitoring site is already used on another project: This site ID is already used on another project. Check the site ID with the monitoring provider."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-MONITORING_SITE_DUPLICATE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_MONITORING_ACCESS_CHANGED:
      summary: MONITORING_ACCESS_CHANGED
      value:
        error:
          code: MONITORING_ACCESS_CHANGED
          message: The monitoring sites changed since you read them. GET the monitoring access again, apply your change, and send it with the new baseSitesHash.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-MONITORING_ACCESS_CHANGED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_MONITORING_ACCESS_LOCKED:
      summary: MONITORING_ACCESS_LOCKED
      value:
        error:
          code: MONITORING_ACCESS_LOCKED
          message: The monitoring sites cannot change right now. The sites are read-only after IC approval. Ask Participate Energy if a site must change.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-MONITORING_ACCESS_LOCKED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_MONITORING_ACCESS_RATE_LIMITED:
      summary: MONITORING_ACCESS_RATE_LIMITED
      value:
        error:
          code: MONITORING_ACCESS_RATE_LIMITED
          message: Too many monitoring site saves on this project. Try again in a few minutes. Wait, then retry.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-MONITORING_ACCESS_RATE_LIMITED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_MONITORING_ACCESS_NOT_ALLOWED:
      summary: MONITORING_ACCESS_NOT_ALLOWED
      value:
        error:
          code: MONITORING_ACCESS_NOT_ALLOWED
          message: Your company cannot change monitoring sites here. Only the project's installer can change the sites. Ask Participate Energy for help.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-MONITORING_ACCESS_NOT_ALLOWED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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. 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/installer/v2/#error-WEBHOOK_URL_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-WEBHOOK_URL_NOT_HTTPS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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/installer/v2/#error-WEBHOOK_URL_PRIVATE_ADDRESS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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 live environment. Set one with PUT /v2/installer/webhooks first.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-WEBHOOK_NOT_CONFIGURED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SANDBOX_SCENARIO_INVALID:
      summary: SANDBOX_SCENARIO_INVALID
      value:
        error:
          code: SANDBOX_SCENARIO_INVALID
          message: "The sandboxScenario 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 scenarios from GET /v2/installer/sandbox/scenarios, or leave it out for project_created."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SANDBOX_SCENARIO_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SANDBOX_DOCUMENT_TYPE_UNKNOWN:
      summary: SANDBOX_DOCUMENT_TYPE_UNKNOWN
      value:
        error:
          code: SANDBOX_DOCUMENT_TYPE_UNKNOWN
          message: The documentType signedFinalPermit is not a document slot of this project. Use a documentType from GET /v2/installer/projects/CA2611-SMIT1/documents.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SANDBOX_DOCUMENT_TYPE_UNKNOWN
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18: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: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SANDBOX_TRANSITION_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_ADDRESS_PO_BOX:
      summary: ADDRESS_PO_BOX
      value:
        error:
          code: ADDRESS_PO_BOX
          message: A site address cannot be a PO Box. Send the street address where the system is installed.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ADDRESS_PO_BOX
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_AMOUNT_OUT_OF_RANGE:
      summary: AMOUNT_OUT_OF_RANGE
      value:
        error:
          code: AMOUNT_OUT_OF_RANGE
          message: The netAmountDue is an amount in US dollars, between 1,000 and 500,000; 2100000 is outside that range. It looks like an amount in cents; send US dollars, for example 60000 for $60,000.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-AMOUNT_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EQUIPMENT_CATEGORY_MISMATCH:
      summary: EQUIPMENT_CATEGORY_MISMATCH
      value:
        error:
          code: EQUIPMENT_CATEGORY_MISMATCH
          message: SKU IQ8PLUS-72 is on the AVL as pv_inverter; send category pv_inverter.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_CATEGORY_MISMATCH
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EQUIPMENT_QUANTITY_OUT_OF_RANGE:
      summary: EQUIPMENT_QUANTITY_OUT_OF_RANGE
      value:
        error:
          code: EQUIPMENT_QUANTITY_OUT_OF_RANGE
          message: The items[0].quantity 5000 is more than 500, the most Participate Energy accepts on one module line. Send the number of units, for example the module count, not the system size in watts.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_QUANTITY_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_EPC_PER_WATT_OUT_OF_RANGE:
      summary: EPC_PER_WATT_OUT_OF_RANGE
      value:
        error:
          code: EPC_PER_WATT_OUT_OF_RANGE
          message: The epcAmount 3200 on a 8 kW DC system is $0.40 per watt, outside the $1.00 to $10.00 per watt Participate Energy prices. Check that epcAmount is the total EPC in US dollars and systemSizeKw is the DC size in kW.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EPC_PER_WATT_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_CONTRACT_DATE_OUT_OF_RANGE:
      summary: CONTRACT_DATE_OUT_OF_RANGE
      value:
        error:
          code: CONTRACT_DATE_OUT_OF_RANGE
          message: The contractDate 2099-01-01 is outside the dates Participate Energy prices. Send a date from 2025-11-12 to 2027-02-10 (one year before today to 90 days after today), as YYYY-MM-DD.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CONTRACT_DATE_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_INCENTIVE_OUT_OF_RANGE:
      summary: INCENTIVE_OUT_OF_RANGE
      value:
        error:
          code: INCENTIVE_OUT_OF_RANGE
          message: The included incentive amount $35,000 is too large for an EPC of $30,000. The amount must be less than the EPC and leave a Net Amount Due of 0 or more. Check the amount, in US dollars.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-INCENTIVE_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_ROOFING_COST_NOT_APPLICABLE:
      summary: ROOFING_COST_NOT_APPLICABLE
      value:
        error:
          code: ROOFING_COST_NOT_APPLICABLE
          message: Roofing costs apply only to systems with solar. Send eligibleRoofingCost and ineligibleRoofingCost as 0, or leave them out, for a battery_only system.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ROOFING_COST_NOT_APPLICABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SYSTEM_SIZE_LOOKS_LIKE_WATTS:
      summary: SYSTEM_SIZE_LOOKS_LIKE_WATTS
      value:
        error:
          code: SYSTEM_SIZE_LOOKS_LIKE_WATTS
          message: The systemSizeKw is in kW DC. 7200 looks like watts; send 7.2.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SYSTEM_SIZE_LOOKS_LIKE_WATTS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SYSTEM_SIZE_OUT_OF_RANGE:
      summary: SYSTEM_SIZE_OUT_OF_RANGE
      value:
        error:
          code: SYSTEM_SIZE_OUT_OF_RANGE
          message: System size is in kW DC, between 0.5 and 250. The systemSizeKw 0.4 is outside that range.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SYSTEM_SIZE_OUT_OF_RANGE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SYSTEM_SIZE_MISMATCH:
      summary: SYSTEM_SIZE_MISMATCH
      value:
        error:
          code: SYSTEM_SIZE_MISMATCH
          message: "The systemSizeKw 80 does not fit the modules: 20 modules x 400 W = 8 kW DC, and the size is more than 25% away from that. Send the DC size in kW that matches the modules, or fix the module quantity."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SYSTEM_SIZE_MISMATCH
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER:
      summary: SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER
      value:
        error:
          code: SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER
          message: Adding a battery changes the system to Solar + Storage, which needs a change order. Contact PE at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_LENDER_NOT_APPROVED:
      summary: LENDER_NOT_APPROVED
      value:
        error:
          code: LENDER_NOT_APPROVED
          message: The lender is not on the Participate Energy approved lender list for this project's state. details[0].approved lists the approved lenders; send one of those names, or null for no lender. To have a lender approved, contact Participate Energy at raceway.support@participate.energy.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-LENDER_NOT_APPROVED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_FILE_EMPTY:
      summary: FILE_EMPTY
      value:
        error:
          code: FILE_EMPTY
          message: The file uploaded for ifu_Q8w2Er5Ty7Ui9Op1As3D is empty (0 bytes). Create a new upload and PUT the whole file.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-FILE_EMPTY
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_UPLOAD_FILE_EMPTY:
      summary: UPLOAD_FILE_EMPTY
      value:
        error:
          code: UPLOAD_FILE_EMPTY
          message: The file for upload iup_Q8w2Er5Ty7Ui9Op1As3D is empty (0 bytes). Create a new upload and PUT the signed customer agreement as a PDF; you can use the same externalId.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-UPLOAD_FILE_EMPTY
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-11T18:02:11.482Z"
    Error_DRAFT_NOT_FOUND:
      summary: DRAFT_NOT_FOUND
      value:
        error:
          code: DRAFT_NOT_FOUND
          message: No contract draft cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K exists for this installer in this environment. List your drafts with GET /v2/installer/contract-drafts.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DRAFT_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_DRAFT_NOT_READY:
      summary: DRAFT_NOT_READY
      value:
        error:
          code: DRAFT_NOT_READY
          message: "Contract draft cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K is not ready to send: 2 issue(s). Fix each issue in details with PATCH /v2/installer/contract-drafts/cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K, then send again."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DRAFT_NOT_READY
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_DRAFT_ALREADY_SENT:
      summary: DRAFT_ALREADY_SENT
      value:
        error:
          code: DRAFT_ALREADY_SENT
          message: Contract draft cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K was already sent, so it cannot be changed or deleted. Read the project's contract status, or void and re-send the contract.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DRAFT_ALREADY_SENT
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_DRAFT_SEND_IN_PROGRESS:
      summary: DRAFT_SEND_IN_PROGRESS
      value:
        error:
          code: DRAFT_SEND_IN_PROGRESS
          message: Contract draft cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K is being sent right now, so it cannot be changed. Read the draft again in a minute.
          retryable: true
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DRAFT_SEND_IN_PROGRESS
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_DRAFT_PORTAL_SEND_UNCONFIRMED:
      summary: DRAFT_PORTAL_SEND_UNCONFIRMED
      value:
        error:
          code: DRAFT_PORTAL_SEND_UNCONFIRMED
          message: The rep started sending contract draft cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K from the Installer Portal and it did not finish. Check the rep's Projects list for this customer before you send again. If no project was created, delete this draft and create a new one.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DRAFT_PORTAL_SEND_UNCONFIRMED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_DRAFT_STATE_INVALID:
      summary: DRAFT_STATE_INVALID
      value:
        error:
          code: DRAFT_STATE_INVALID
          message: Contract draft cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K was changed outside the API and no longer points to a project your integration created from it, so it was not sent. Check the rep's Projects list for this customer before you create a new draft.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DRAFT_STATE_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_ASSIGNEE_NOT_FOUND:
      summary: ASSIGNEE_NOT_FOUND
      value:
        error:
          code: ASSIGNEE_NOT_FOUND
          message: The assignedToEmail is not an active user of this installer. Send the email of an active Installer Portal user of your organization, or leave it out to assign the draft to the X-PE-Actor-Email user.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ASSIGNEE_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_ASSIGNEE_NOT_PERMITTED:
      summary: ASSIGNEE_NOT_PERMITTED
      value:
        error:
          code: ASSIGNEE_NOT_PERMITTED
          message: "The assigned user has the role finance, which cannot create projects. Assign a user with one of these roles: administrator, editor, operations."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ASSIGNEE_NOT_PERMITTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PREFILL_LOCKED_FIELD:
      summary: PREFILL_LOCKED_FIELD
      value:
        error:
          code: PREFILL_LOCKED_FIELD
          message: Your organization's prefill locks financials.dcBonusRecipient to "installer" for this state. Leave financials.dcBonusRecipient out, or send the locked value. GET /v2/installer/contract-drafts/defaults?stateCode=CA lists the locked fields.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PREFILL_LOCKED_FIELD
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_EQUIPMENT_NOT_ALLOWED_BY_PREFILL:
      summary: EQUIPMENT_NOT_ALLOWED_BY_PREFILL
      value:
        error:
          code: EQUIPMENT_NOT_ALLOWED_BY_PREFILL
          message: Your organization's prefill does not allow Example Solar - EX400 (pv_module) in CA. Choose another item; GET /v2/installer/contract-drafts/defaults?stateCode=CA lists the excluded items.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_NOT_ALLOWED_BY_PREFILL
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_DRAFT_FIELD_REQUIRED:
      summary: DRAFT_FIELD_REQUIRED
      value:
        error:
          code: DRAFT_FIELD_REQUIRED
          message: A field the contract needs is missing. The issue names the field; send it with PATCH /v2/installer/contract-drafts/cdr_7Hq2Lm9Xc4Rt8Vb1Nz6K.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DRAFT_FIELD_REQUIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_DRAFT_FIELD_INVALID:
      summary: DRAFT_FIELD_INVALID
      value:
        error:
          code: DRAFT_FIELD_INVALID
          message: A field value is not in the form the contract needs (an email, a phone with 10 or 11 digits, or a ZIP code). The issue names the field.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-DRAFT_FIELD_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PAYMENTS_DO_NOT_SUM:
      summary: PAYMENTS_DO_NOT_SUM
      value:
        error:
          code: PAYMENTS_DO_NOT_SUM
          message: The payments must add up to the Net Amount Due to the cent. Change the payment amounts so they match.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PAYMENTS_DO_NOT_SUM
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PAYMENT_ONE_TOO_HIGH:
      summary: PAYMENT_ONE_TOO_HIGH
      value:
        error:
          code: PAYMENT_ONE_TOO_HIGH
          message: Payment 1 (due at signing) may be at most the lower of $1,000 ($500 in New York and New Jersey) and 10% of the Net Amount Due. Lower Payment 1 and move the rest to a later payment.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PAYMENT_ONE_TOO_HIGH
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PAYMENT_EXCEEDS_NET_AMOUNT_DUE:
      summary: PAYMENT_EXCEEDS_NET_AMOUNT_DUE
      value:
        error:
          code: PAYMENT_EXCEEDS_NET_AMOUNT_DUE
          message: A payment is larger than the Net Amount Due. Lower it.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PAYMENT_EXCEEDS_NET_AMOUNT_DUE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_ADDITIONAL_PRODUCT_EXCEEDS_EPC:
      summary: ADDITIONAL_PRODUCT_EXCEEDS_EPC
      value:
        error:
          code: ADDITIONAL_PRODUCT_EXCEEDS_EPC
          message: An additional product amount is larger than the EPC amount. Check the amount; it is in USD.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-ADDITIONAL_PRODUCT_EXCEEDS_EPC
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PTO_BEFORE_INSTALL:
      summary: PTO_BEFORE_INSTALL
      value:
        error:
          code: PTO_BEFORE_INSTALL
          message: The forecasted PTO date must be after the forecasted install start date. Send sales.ptoDate later than sales.installStartDate.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PTO_BEFORE_INSTALL
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_MILESTONE_NAME_INVALID:
      summary: MILESTONE_NAME_INVALID
      value:
        error:
          code: MILESTONE_NAME_INVALID
          message: Each payment milestone name must be 5 to 30 characters. Rename the milestone the issue names.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-MILESTONE_NAME_INVALID
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_COSIGNER_EMAIL_SAME_AS_CUSTOMER:
      summary: COSIGNER_EMAIL_SAME_AS_CUSTOMER
      value:
        error:
          code: COSIGNER_EMAIL_SAME_AS_CUSTOMER
          message: "The cosigner email must differ from the customer email: each signer gets their own signing link. Send the cosigner's own email."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-COSIGNER_EMAIL_SAME_AS_CUSTOMER
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_EQUIPMENT_MANUFACTURER_MISMATCH:
      summary: EQUIPMENT_MANUFACTURER_MISMATCH
      value:
        error:
          code: EQUIPMENT_MANUFACTURER_MISMATCH
          message: "The inverter and battery manufacturers differ. Confirm the pairing with system.confirmManufacturerMismatch: true, or change the equipment."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_MANUFACTURER_MISMATCH
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PRICING_NOT_CALCULATED:
      summary: PRICING_NOT_CALCULATED
      value:
        error:
          code: PRICING_NOT_CALCULATED
          message: The lease price of the draft has not been calculated yet. The issue lists the pricing inputs to send.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PRICING_NOT_CALCULATED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PRICING_STALE:
      summary: PRICING_STALE
      value:
        error:
          code: PRICING_STALE
          message: A pricing input changed after the lease price was calculated (for example in the Installer Portal). Update the draft with PATCH so the price is calculated again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PRICING_STALE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_AUTO_SIGNER_REQUIRED:
      summary: AUTO_SIGNER_REQUIRED
      value:
        error:
          code: AUTO_SIGNER_REQUIRED
          message: Nobody at your company is set up to sign the customer agreement automatically, so it cannot be sent. No signer is set up for this version of the agreement. Ask your administrator to set up a default signer in E-sign Setup in the Installer Portal, then send again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-AUTO_SIGNER_REQUIRED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_CONTRACT_TEMPLATE_NOT_FOUND:
      summary: CONTRACT_TEMPLATE_NOT_FOUND
      value:
        error:
          code: CONTRACT_TEMPLATE_NOT_FOUND
          message: There is no customer agreement ready for CA for your company yet, so the contract cannot be sent. Ask Participate Energy at raceway.support@participate.energy to publish one, then send again.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CONTRACT_TEMPLATE_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_CONTRACT_NOT_SENDABLE:
      summary: CONTRACT_NOT_SENDABLE
      value:
        error:
          code: CONTRACT_NOT_SENDABLE
          message: "Participate Energy could not send the contract: Missing mandatory fields: customer_initials_9. Fix the cause, then send again. When details name a projectId, the project was created; send its contract with POST /v2/installer/projects/<projectId>/contract-esign/send."
          retryable: false
          details:
            - field: ""
              issue: The project was created; only the e-sign send failed. Send it again with POST /v2/installer/projects/CA2611-EXAM1/contract-esign/send.
              projectId: CA2611-EXAM1
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CONTRACT_NOT_SENDABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_CONTRACT_SEND_FAILED:
      summary: CONTRACT_SEND_FAILED
      value:
        error:
          code: CONTRACT_SEND_FAILED
          message: The contract for project CA2611-EXAM1 could not be sent because of an error at Participate Energy. The project exists. Retry the send in a few minutes with POST /v2/installer/projects/CA2611-EXAM1/contract-esign/send.
          retryable: true
          details:
            - field: ""
              issue: The project was created; only the e-sign send failed. Send it again with POST /v2/installer/projects/CA2611-EXAM1/contract-esign/send.
              projectId: CA2611-EXAM1
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CONTRACT_SEND_FAILED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PACKET_NOT_FOUND:
      summary: PACKET_NOT_FOUND
      value:
        error:
          code: PACKET_NOT_FOUND
          message: Project CA2611-EXAM1 has no contract sent for e-signature. Send one with POST /v2/installer/contract-drafts/<draftId>/send or POST /v2/installer/projects/CA2611-EXAM1/contract-esign/send.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PACKET_NOT_FOUND
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_PACKET_NOT_VOIDABLE:
      summary: PACKET_NOT_VOIDABLE
      value:
        error:
          code: PACKET_NOT_VOIDABLE
          message: The contract for project CA2611-EXAM1 is completed, so it cannot be voided. Read it with GET /v2/installer/projects/CA2611-EXAM1/contract-esign.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-PACKET_NOT_VOIDABLE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_CONTRACT_ALREADY_SIGNED:
      summary: CONTRACT_ALREADY_SIGNED
      value:
        error:
          code: CONTRACT_ALREADY_SIGNED
          message: "The contract for project CA2611-EXAM1 is signed (completed), so it is not sent again. Read it with GET /v2/installer/projects/CA2611-EXAM1/contract-esign. A change to a signed contract needs a change order through Participate Energy."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CONTRACT_ALREADY_SIGNED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_INSTALL_BEFORE_CONTRACT:
      summary: INSTALL_BEFORE_CONTRACT
      value:
        error:
          code: INSTALL_BEFORE_CONTRACT
          message: "The forecasted install start date cannot be before the contract date. Send sales.installStartDate on or after sales.contractDate."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-INSTALL_BEFORE_CONTRACT
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_EQUIPMENT_NOT_FOR_SYSTEM_TYPE:
      summary: EQUIPMENT_NOT_FOR_SYSTEM_TYPE
      value:
        error:
          code: EQUIPMENT_NOT_FOR_SYSTEM_TYPE
          message: "The equipment does not fit the system type: a Solar Only system has no battery. Send systemType PV+Storage, or leave the battery out."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-EQUIPMENT_NOT_FOR_SYSTEM_TYPE
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_COSIGNER_NOT_SUPPORTED:
      summary: COSIGNER_NOT_SUPPORTED
      value:
        error:
          code: COSIGNER_NOT_SUPPORTED
          message: "The customer agreement for this state has no place for a cosigner to sign. Remove the cosigner (cosigner: null), or ask Participate Energy to add a cosigner signature to the agreement."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-COSIGNER_NOT_SUPPORTED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_CONTRACT_DATA_MISSING:
      summary: CONTRACT_DATA_MISSING
      value:
        error:
          code: CONTRACT_DATA_MISSING
          message: "The customer agreement needs a value that does not come from the draft (it is read from your organization's settings or Participate Energy's records). The issue names it. Ask Participate Energy at raceway.support@participate.energy."
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CONTRACT_DATA_MISSING
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
    Error_CONTRACT_ESIGN_MOVED:
      summary: CONTRACT_ESIGN_MOVED
      value:
        error:
          code: CONTRACT_ESIGN_MOVED
          message: POST /v2/installer/contract-esign was replaced in 2.2. Send a contract draft with POST /v2/installer/contract-drafts/<draftId>/send, or send the contract of an existing project again with POST /v2/installer/projects/<projectId>/contract-esign/send.
          retryable: false
          details: []
          docsUrl: https://api.participate.energy/docs/installer/v2/#error-CONTRACT_ESIGN_MOVED
        meta:
          requestId: req_9Bv4Nc7Xz2Lk5Hj8Gf3D
          environment: live
          timestamp: "2026-11-12T18:02:11.482Z"
  schemas:
    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.
          pattern: ^\d{5}(-\d{4})?$
      description: A US site address.
    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.
    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"
    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.
          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
                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
          minLength: 1
          maxLength: 64
          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
        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:
        mismatches:
          type: array
          description: "v2.2: each field where Google's result differs from the address you sent (zipCode, city or stateCode). Empty when they agree."
          items:
            type: object
            additionalProperties: false
            required:
              - field
              - sent
              - resolved
            properties:
              field:
                type: string
                enum:
                  - zipCode
                  - city
                  - stateCode
              sent:
                type: string
              resolved:
                type: string
        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.
      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.
    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:
        - systemType
        - insuranceOption
        - address
        - pvDomesticContent
        - storageDomesticContent
        - energyCommunity
        - dcBonusRecipient
      properties:
        epcAmount:
          type: number
          description: "The total EPC before tax, in USD: 1,000 to 500,000 (v2.2). Required on the epc basis. Leave it out on the netAmountDue basis."
        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. The string "1", "2" or "3" is accepted too.
        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.
        systemSizeKw:
          type: number
          description: "Optional (v2.2): the system size in kW DC, 0.5 to 250. Not used by the math; with it the EPC must be $1 to $10 per watt DC 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 (EPC_PER_WATT_OUT_OF_RANGE). A value in watts is refused (SYSTEM_SIZE_LOOKS_LIKE_WATTS), never converted."
        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."
        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
        basis:
          type: string
          enum:
            - epc
            - netAmountDue
          description: Price from the EPC (default) or solve the EPC from targetNetAmountDue.
        targetNetAmountDue:
          type: number
          description: "netAmountDue basis only: the Net Amount Due to price backward from, in USD: 1,000 to 500,000 (v2.2; outside it EPC_OUT_OF_RANGE)."
    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
      properties:
        systemSizeKw:
          type:
            - number
            - "null"
          description: The systemSizeKw sent (v2.2), or null.
        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
      description: The inputs PE priced, after defaults and lookups.
    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"
    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: energyCommunity was sent as true, but the Energy Community check found that the address does not qualify. The quote is priced with energyCommunity false.
        ENERGY_COMMUNITY_NOT_VERIFIED: energyCommunity was sent as true and the Energy Community check could not run, so the quote uses true as sent. PE confirms Energy Community in review.
        FIELD_NOT_APPLICABLE: A flag that does not apply to the system type (for example storageDomesticContent on solar_only). It does not change the quote.
        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.
    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 (v2.2 warnings).
    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 before tax, in USD: 1,000 to 500,000 (v2.2)."
        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. The string "1", "2" or "3" is accepted too.
        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.
        systemSizeKw:
          type: number
          description: "Optional (v2.2): the system size in kW DC, 0.5 to 250. Not used by the math; with it the EPC must be $1 to $10 per watt DC 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 (EPC_PER_WATT_OUT_OF_RANGE). A value in watts is refused (SYSTEM_SIZE_LOOKS_LIKE_WATTS), never converted."
        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."
        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
        dppProduct:
          type: string
          enum:
            - Installment
            - Classic DPP
            - Escalator
        term:
          type: integer
          enum:
            - 5
            - 10
            - 15
            - 20
            - 25
            - 30
          description: Years. At most 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"
    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
    LeasePriceQuote:
      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
        - basis
        - epcAmount
        - targetNetAmountDue
      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"
        basis:
          type: string
          enum:
            - epc
            - netAmountDue
        epcAmount:
          type: number
          description: "The EPC the quote used: the one you sent, or the solved one."
        targetNetAmountDue:
          type:
            - number
            - "null"
          description: The target you sent on the netAmountDue basis. Null on the epc basis.
      description: A lease quote, with the basis it was priced on.
    Environment:
      type: string
      enum:
        - test
        - live
      description: "The key environment: test (Test key, ik_test_) or live (production key, ik_live_)."
    Scope:
      type: string
      enum:
        - avl:read
        - eligibility:read
        - pricing:lease
        - pricing:sungage
        - projects:create
        - projects:read
        - projects:write
        - documents:write
        - actions:write
        - webhooks:manage
        - contracts:write
        - contracts:send
      description: A key scope.
      x-enum-descriptions:
        avl:read: Read the Approved Vendor List (AVL), your Safe Harbor opportunities and their custom AVL items, utilities, your active states, your Equipment Map and the reference lists (insurance options, document types, photo categories, project statuses, milestones).
        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.
        pricing:sungage: List Sungage products and price a Participate Energy lease with a Sungage loan.
        projects:create: Create projects by uploading signed customer contracts, and read the status of those uploads.
        projects:read: List and read your projects, their documents, photos, activity, Actions and monitoring access.
        projects:write: Update project fields, financials, equipment and the Safe Harbor opportunity.
        documents:write: Upload documents and photos, archive or restore a document version, and save monitoring site IDs.
        actions:write: Resolve Actions with a note and add notes to Actions.
        webhooks:manage: Register a webhook endpoint and receive the IC and PC approval events and the new Action events for your projects.
        contracts:write: Create, read, update, validate and delete Contract Builder drafts that your sales reps finish and send from the Installer Portal.
        contracts:send: Send a contract draft for e-signature, which creates the project and emails the contract to the homeowner (and cosigner) to sign, and void or re-send a contract.
    ErrorCode:
      type: string
      enum:
        - AUTH_HEADER_MISSING
        - AUTH_HEADER_MALFORMED
        - KEY_IS_V1
        - KEY_IS_DESIGN_API
        - KEY_INVALID
        - KEY_REVOKED
        - KEY_EXPIRED
        - INSTALLER_API_SUSPENDED
        - ENVIRONMENT_NOT_ENABLED
        - INSTALLER_NOT_ELIGIBLE
        - SANDBOX_ONLY
        - SCOPE_NOT_GRANTED
        - ACTOR_NOT_ON_ROSTER
        - ROUTE_NOT_FOUND
        - RESOURCE_NOT_FOUND
        - METHOD_NOT_ALLOWED
        - EXTERNAL_ID_AMBIGUOUS
        - BODY_TOO_LARGE
        - UNSUPPORTED_MEDIA_TYPE
        - INVALID_JSON
        - VALIDATION_FAILED
        - UNKNOWN_FIELD
        - CURSOR_INVALID
        - ACTOR_REQUIRED
        - ACTOR_INVALID_EMAIL
        - RATE_LIMITED
        - DAILY_QUOTA_EXCEEDED
        - NOT_IMPLEMENTED
        - NOT_YET_AVAILABLE
        - UPSTREAM_TIMEOUT
        - SERVICE_DISABLED
        - INTERNAL_ERROR
        - ADDRESS_NOT_FOUND
        - ADDRESS_OUTSIDE_US
        - STATE_NOT_SUPPORTED
        - STATE_MISMATCH
        - STATE_NOT_ACTIVE_FOR_INSTALLER
        - PRODUCT_NOT_ENABLED
        - UTILITY_NOT_FOUND
        - OWNERSHIP_NOT_ELIGIBLE
        - EXISTING_SOLAR_NOT_ELIGIBLE
        - SAFE_HARBOR_OPPORTUNITY_NOT_FOUND
        - EQUIPMENT_NOT_ON_AVL
        - EQUIPMENT_AMBIGUOUS
        - SALES_TAX_UNRESOLVED
        - EC_LOOKUP_UNAVAILABLE
        - TAX_RATE_UNAVAILABLE
        - ADDRESS_LOOKUP_UNAVAILABLE
        - EPC_OUT_OF_RANGE
        - NET_AMOUNT_DUE_OUT_OF_RANGE
        - ROOFING_COST_INVALID
        - SAFE_HARBOR_UNITS_INVALID
        - INCENTIVE_NOT_AVAILABLE
        - SUNGAGE_NOT_ENROLLED
        - SUNGAGE_USER_NOT_REGISTERED
        - SUNGAGE_PRODUCT_UNAVAILABLE
        - SUNGAGE_UNAVAILABLE
        - INSTALLER_ON_HOLD
        - PRODUCT_NOT_AVAILABLE_IN_STATE
        - PRODUCT_NOT_SUPPORTED_BY_API
        - EXTERNAL_ID_IN_USE
        - SANDBOX_FIELD_IN_LIVE
        - UPLOAD_ALREADY_SUBMITTED
        - UPLOAD_URL_EXPIRED
        - UPLOAD_FILE_MISSING
        - UPLOAD_FILE_TOO_LARGE
        - UPLOAD_NOT_PDF
        - PROJECT_CANCELLED
        - PROJECT_LOCKED
        - CHANGE_ORDER_REQUIRED
        - CHANGE_ORDER_BLOCKED
        - PROJECT_CHANGED_SINCE_READ
        - EXTERNAL_ID_TAKEN
        - FIELD_NOT_EDITABLE
        - UTILITY_NOT_RECOGNIZED
        - PROJECT_UPDATE_REJECTED
        - FINANCIALS_SET_BY_PE
        - FINANCIALS_INVALID
        - FINANCIALS_EQUIPMENT_UNRESOLVED
        - EQUIPMENT_WRONG_CATEGORY
        - EQUIPMENT_INVALID
        - EQUIPMENT_DOCUMENTS_SIGNED
        - SAFE_HARBOR_WRONG_INSTALLER
        - SAFE_HARBOR_NOT_FOR_DM
        - SAFE_HARBOR_OPPORTUNITY_CLOSED
        - SAFE_HARBOR_NO_UNITS
        - SAFE_HARBOR_NOT_APPLICABLE
        - SAFE_HARBOR_CONSUMED
        - DOCUMENT_TYPE_NOT_UPLOADABLE
        - PHOTOS_USE_PHOTO_UPLOAD
        - DOCUMENT_UPLOAD_CLOSED
        - DOCUMENT_LOCKED
        - CONTENT_TYPE_NOT_ALLOWED
        - FILE_NOT_RECEIVED
        - FILE_UPLOAD_EXPIRED
        - FILE_UPLOAD_IN_PROGRESS
        - FILE_TOO_LARGE
        - FILE_CONTENT_MISMATCH
        - DOCUMENT_ARCHIVE_BLOCKED
        - PHOTO_CATEGORY_UNKNOWN
        - MONITORING_ACCESS_INVALID
        - MONITORING_SITE_DUPLICATE
        - MONITORING_ACCESS_CHANGED
        - MONITORING_ACCESS_LOCKED
        - MONITORING_ACCESS_RATE_LIMITED
        - MONITORING_ACCESS_NOT_ALLOWED
        - WEBHOOK_URL_INVALID
        - WEBHOOK_URL_NOT_HTTPS
        - WEBHOOK_URL_PRIVATE_ADDRESS
        - WEBHOOK_NOT_CONFIGURED
        - SANDBOX_SCENARIO_INVALID
        - SANDBOX_DOCUMENT_TYPE_UNKNOWN
        - SANDBOX_TRANSITION_INVALID
        - ADDRESS_PO_BOX
        - AMOUNT_OUT_OF_RANGE
        - EQUIPMENT_CATEGORY_MISMATCH
        - EQUIPMENT_QUANTITY_OUT_OF_RANGE
        - EPC_PER_WATT_OUT_OF_RANGE
        - CONTRACT_DATE_OUT_OF_RANGE
        - CONTRACT_DATE_BEFORE_RETITC_CUTOFF
        - INCENTIVE_OUT_OF_RANGE
        - ROOFING_COST_NOT_APPLICABLE
        - SYSTEM_SIZE_LOOKS_LIKE_WATTS
        - SYSTEM_SIZE_OUT_OF_RANGE
        - SYSTEM_SIZE_MISMATCH
        - SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER
        - LENDER_NOT_APPROVED
        - FILE_EMPTY
        - UPLOAD_FILE_EMPTY
        - DRAFT_NOT_FOUND
        - DRAFT_NOT_READY
        - DRAFT_ALREADY_SENT
        - DRAFT_SEND_IN_PROGRESS
        - DRAFT_PORTAL_SEND_UNCONFIRMED
        - DRAFT_STATE_INVALID
        - ASSIGNEE_NOT_FOUND
        - ASSIGNEE_NOT_PERMITTED
        - PREFILL_LOCKED_FIELD
        - EQUIPMENT_NOT_ALLOWED_BY_PREFILL
        - DRAFT_FIELD_REQUIRED
        - DRAFT_FIELD_INVALID
        - PAYMENTS_DO_NOT_SUM
        - PAYMENT_ONE_TOO_HIGH
        - PAYMENT_EXCEEDS_NET_AMOUNT_DUE
        - ADDITIONAL_PRODUCT_EXCEEDS_EPC
        - PTO_BEFORE_INSTALL
        - INSTALL_BEFORE_CONTRACT
        - EQUIPMENT_NOT_FOR_SYSTEM_TYPE
        - COSIGNER_NOT_SUPPORTED
        - CONTRACT_DATA_MISSING
        - MILESTONE_NAME_INVALID
        - COSIGNER_EMAIL_SAME_AS_CUSTOMER
        - EQUIPMENT_MANUFACTURER_MISMATCH
        - PRICING_NOT_CALCULATED
        - PRICING_STALE
        - AUTO_SIGNER_REQUIRED
        - CONTRACT_TEMPLATE_NOT_FOUND
        - CONTRACT_NOT_SENDABLE
        - CONTRACT_SEND_FAILED
        - PACKET_NOT_FOUND
        - PACKET_NOT_VOIDABLE
        - CONTRACT_ALREADY_SIGNED
        - CONTRACT_ESIGN_MOVED
        - STATE_FIELDS_UNAVAILABLE
      description: Every error code. The description of each value is the message template. See Errors in the introduction.
      x-enum-descriptions:
        AUTH_HEADER_MISSING: "The request has no Authorization header. Send \"Authorization: Bearer <key>\" with your Installer API key. Keys start with ik_test_ or ik_live_."
        AUTH_HEADER_MALFORMED: "The Authorization header does not hold an Installer API key. Send \"Authorization: Bearer <key>\", where the key starts with ik_test_ or ik_live_ followed by 40 letters and digits, with no spaces or line breaks."
        KEY_IS_V1: This is an Installer API v1 key (it starts with pk_). v1 keys work only at https://api.participate.energy/v1. Use an Installer API v2 key (ik_test_ or ik_live_) here, or ask Participate Energy for one at raceway.support@participate.energy.
        KEY_IS_DESIGN_API: This is a Design API credential or access token. Design API credentials work only at https://api.participate.energy/v2/design. The Installer API v2 takes an installer key that starts with ik_test_ or ik_live_.
        KEY_INVALID: The key is not recognized. Check that the full key was copied without spaces, or ask Participate Energy for a new key at raceway.support@participate.energy.
        KEY_REVOKED: The key {keyPrefix} was revoked. Use another active key, or ask Participate Energy for a new one at raceway.support@participate.energy.
        KEY_EXPIRED: The key {keyPrefix} expired at {expiredAt}. Keys last 12 months; ask Participate Energy for a new key at raceway.support@participate.energy.
        INSTALLER_API_SUSPENDED: Installer 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 key for an enabled environment, or ask Participate Energy to enable it.
        INSTALLER_NOT_ELIGIBLE: Your organization is not set up as a Participate Energy install partner, so this key cannot be used. Contact Participate Energy at raceway.support@participate.energy.
        SANDBOX_ONLY: This endpoint works only with Test keys (ik_test_). Send the request with your Test key.
        SCOPE_NOT_GRANTED: "This endpoint needs the scope {scope}, and your key does not carry it. The key carries: {granted}. Ask Participate Energy for a key with the scope you need."
        ACTOR_NOT_ON_ROSTER: The X-PE-Actor-Email address is not an active Raceway user of your company, and its domain is not one of your allowed domains. Send the email of the person doing the work as Raceway knows it, or add the user in Raceway first.
        ROUTE_NOT_FOUND: No Installer API route matches {received}. Check the method and path against the API reference at https://api.participate.energy/docs/installer/v2/.
        RESOURCE_NOT_FOUND: No {resource} with this id is available to your key in the {environment} environment. Check the id, and use a key for the environment where the {resource} was created.
        METHOD_NOT_ALLOWED: "The method {method} is not allowed on {path}. Allowed methods: {allowed}."
        EXTERNAL_ID_AMBIGUOUS: More than one of your projects uses the externalId {externalId}. Read the project by its projectId instead; the projectIds are in details.
        BODY_TOO_LARGE: The request body is {received} bytes, more than the {max} bytes allowed. Send a smaller JSON body.
        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: {fields}. Allowed fields: {allowed}. Remove the other fields and send the request again."
        CURSOR_INVALID: The cursor is not valid for this list. Send the nextCursor from the previous page of the same request without changes, or leave cursor out to start at the first page.
        ACTOR_REQUIRED: This endpoint needs the X-PE-Actor-Email header. Send the email of the person doing the work (for example your sales rep) as Raceway knows it.
        ACTOR_INVALID_EMAIL: The X-PE-Actor-Email header is not a valid email address. Send one email address, for example rep@installer.example.
        RATE_LIMITED: "Too many requests: the limit is {limit} {window}. Wait for the Retry-After seconds, then retry."
        DAILY_QUOTA_EXCEEDED: Your company used its daily limit of {limit} {quota} in the {environment} environment. The limit resets at {resetAt}; retry after that.
        NOT_IMPLEMENTED: This endpoint is not available yet. See https://api.participate.energy/docs/installer/v2/ for the endpoints that work today.
        NOT_YET_AVAILABLE: This feature is not available in the Installer API yet. See https://api.participate.energy/docs/installer/v2/ for the endpoints that work today.
        UPSTREAM_TIMEOUT: A service this request depends on did not answer in time. Retry the same request in a few minutes.
        SERVICE_DISABLED: The Installer API is turned off for now by Participate Energy. Retry later, or ask raceway.support@participate.energy for the status.
        INTERNAL_ERROR: An unexpected error occurred while handling request {requestId}. Retry after waits of 1, 2, 4, 8 and 16 seconds, and stop after 5 tries. If it still fails, send the request id to raceway.support@participate.energy.
        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_OUTSIDE_US: The address is not in the United States. Participate Energy works with US addresses only.
        STATE_NOT_SUPPORTED: Participate Energy does not operate in {stateCode}. Use a state from GET /v2/installer/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.
        STATE_NOT_ACTIVE_FOR_INSTALLER: The installer is not active in {stateCode}. Use a state from GET /v2/installer/states, or request the state in the Installer Portal.
        PRODUCT_NOT_ENABLED: The product {productType} is not enabled for this installer. Contact Participate Energy to turn it on.
        UTILITY_NOT_FOUND: The utility is not on the list for {stateCode}. Use a name from GET /v2/installer/utilities, sending the zipCode of the site address.
        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.
        SAFE_HARBOR_OPPORTUNITY_NOT_FOUND: No Safe Harbor opportunity {opportunityId} belongs to this installer. Use an opportunityId from GET /v2/installer/safe-harbor/opportunities.
        EQUIPMENT_NOT_ON_AVL: The equipment {sku} is not on the Participate Energy approved vendor list. Use a SKU from GET /v2/installer/avl.
        EQUIPMENT_AMBIGUOUS: The equipment {sku} matches more than one item on the approved vendor list. Send the exact SKU from GET /v2/installer/avl.
        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.
        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 where the endpoint allows it.
        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.
        EPC_OUT_OF_RANGE: The {field} is {amountName} in US dollars, between {min} and {max}; {received} is outside that range. {hint}.
        NET_AMOUNT_DUE_OUT_OF_RANGE: "The targetNetAmountDue {received} cannot be priced: the EPC that gives it must be from {min} to {max} USD. Check the amount and the other inputs."
        ROOFING_COST_INVALID: "The roofing costs are not valid: {reason}. Send amounts of 0 or more, in USD."
        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.
        INCENTIVE_NOT_AVAILABLE: "The incentive {received} is not available: {reason}."
        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. 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 in the X-PE-Actor-Email header, or register the user with Sungage.
        SUNGAGE_PRODUCT_UNAVAILABLE: The Sungage product, term or rate is not available for this installer and project. Use a combination from GET /v2/installer/pricing/sungage/products.
        SUNGAGE_UNAVAILABLE: Sungage is unavailable right now. Retry the same request in a few minutes.
        INSTALLER_ON_HOLD: This installer cannot create new projects right now because its account is on hold. Contact Participate Energy at raceway.support@participate.energy.
        PRODUCT_NOT_AVAILABLE_IN_STATE: The product {productType} is not available in {stateCode}. Send a stateCode where Participate Energy offers the product, or contact raceway.support@participate.energy.
        PRODUCT_NOT_SUPPORTED_BY_API: Contract uploads through the API support Synthetic Cash only. Upload Distributed Microgrid contracts in the Installer Portal.
        EXTERNAL_ID_IN_USE: The externalId {externalId} is already used by this installer. {reason} To create another project, send a different externalId.
        SANDBOX_FIELD_IN_LIVE: The field {field} works only with a test key. Remove it from requests made with a live key.
        UPLOAD_ALREADY_SUBMITTED: Upload {uploadId} was already submitted and is now {status}. Poll GET /v2/installer/contract-uploads/{uploadId} for the result instead of submitting again.
        UPLOAD_URL_EXPIRED: The upload URL for upload {uploadId} expired before a file arrived. Create a new upload with POST /v2/installer/contract-uploads; you can use the same externalId.
        UPLOAD_FILE_MISSING: No file was found for upload {uploadId}. PUT the PDF to the uploadUrl with the uploadHeaders first, then submit.
        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 externalId.
        UPLOAD_NOT_PDF: The file for upload {uploadId} is not a PDF. Create a new upload and PUT the signed customer agreement as a PDF; you can use the same externalId.
        PROJECT_CANCELLED: Project {projectId} was cancelled, so it cannot be changed. You can still read it. If this is a mistake, contact Participate Energy at raceway.support@participate.energy.
        PROJECT_LOCKED: Project {projectId} cannot be edited at the {milestone} milestone. {reason} If a value must change, contact Participate Energy at raceway.support@participate.energy.
        CHANGE_ORDER_REQUIRED: "Project {projectId} passed IC approval, so its {area} can no longer be changed through the API. A change now needs a signed change order: upload it as the project's change order document, or contact Participate Energy at raceway.support@participate.energy."
        CHANGE_ORDER_BLOCKED: This change to project {projectId} needs Participate Energy review and cannot be made through the API. Contact Participate Energy at raceway.support@participate.energy.
        PROJECT_CHANGED_SINCE_READ: Project {projectId} changed after you read it. Your expectedUpdatedAt is {expected} but the project's updatedAt is {actual}. Read the project again, then resend the change.
        EXTERNAL_ID_TAKEN: This externalId is already used by project {otherProjectId} of your company. Each project needs its own externalId. Send a different one.
        FIELD_NOT_EDITABLE: "\"{field}\" cannot be set through the API. {hint} Remove the field and send the request again."
        UTILITY_NOT_RECOGNIZED: The utility name is not in the Participate Energy utility list. Use a name from GET /utilities, sending the zipCode of the project site, and send the change again.
        PROJECT_UPDATE_REJECTED: Participate Energy could not save the change because {count} value(s) failed validation. See details, fix the values and send the change again.
        FINANCIALS_SET_BY_PE: Financials on Distributed Microgrid projects are set by PE. Contact PE to change them.
        FINANCIALS_INVALID: The financials for project {projectId} cannot be computed from these inputs. See details, fix the inputs and send them again.
        FINANCIALS_EQUIPMENT_UNRESOLVED: Project {projectId} has equipment that is not matched to the approved vendor list yet, so its lease factor is not final. Fix the equipment first with PUT /projects/{projectId}/equipment, then update the financials.
        EQUIPMENT_WRONG_CATEGORY: "Equipment items that point to an approved vendor list item of another category: {count}. See details, then send each item under its own category."
        EQUIPMENT_INVALID: The equipment change was not accepted ({count} problem(s)). See details, fix the items and send the change again.
        EQUIPMENT_DOCUMENTS_SIGNED: Project {projectId} has {count} signed document(s) that list its current equipment, such as a Bill of Sale. Changing the equipment voids them, which needs a confirmation in the Installer Portal. Make this equipment change in the portal, or contact Participate Energy at raceway.support@participate.energy.
        SAFE_HARBOR_WRONG_INSTALLER: Safe Harbor opportunity {opportunityId} belongs to another company in your organization. Pick an opportunity that belongs to the installer of project {projectId}.
        SAFE_HARBOR_NOT_FOR_DM: Safe Harbor does not apply to Distributed Microgrid projects. Contact PE if this project needs a Safe Harbor opportunity.
        SAFE_HARBOR_OPPORTUNITY_CLOSED: Safe Harbor opportunity {opportunityId} is {status} and can no longer be linked. Pick an opportunity that is still open.
        SAFE_HARBOR_NO_UNITS: Safe Harbor opportunity {opportunityId} has no units left. Pick another opportunity, or contact Participate Energy at raceway.support@participate.energy.
        SAFE_HARBOR_NOT_APPLICABLE: "Safe Harbor opportunity {opportunityId} cannot be linked to project {projectId}: the project does not meet the opportunity's rules (for example, its equipment is not on the opportunity's custom AVL). Check the equipment, or contact Participate Energy at raceway.support@participate.energy."
        SAFE_HARBOR_CONSUMED: Project {projectId} already used Safe Harbor units, so its opportunity cannot be unlinked through the API. Contact Participate Energy at raceway.support@participate.energy.
        DOCUMENT_TYPE_NOT_UPLOADABLE: The document type {documentType} is not one you can upload on project {projectId}. GET /v2/installer/projects/{projectId}/documents lists the document types you can upload.
        PHOTOS_USE_PHOTO_UPLOAD: Photos are not uploaded as a document. Use POST /v2/installer/projects/{projectId}/photos/{category}/uploads with the photo category instead.
        DOCUMENT_UPLOAD_CLOSED: "Uploads of {documentType} are closed on project {projectId}: {reason} Ask Participate Energy if a file still needs to change."
        DOCUMENT_LOCKED: This document cannot change right now. {reason} Ask Participate Energy if it must change.
        CONTENT_TYPE_NOT_ALLOWED: "This content type is not accepted for {what}. Send one of: {allowed}."
        FILE_NOT_RECEIVED: No file has arrived for upload {fileUploadId} yet. PUT the file to uploadUrl with the uploadHeaders, then confirm again.
        FILE_UPLOAD_EXPIRED: The upload URL for {fileUploadId} expired before the file arrived. Create a new upload and send the file within 15 minutes.
        FILE_UPLOAD_IN_PROGRESS: Upload {fileUploadId} is being confirmed by another request. Wait a few seconds, then confirm again to read the result.
        FILE_TOO_LARGE: The file uploaded for {fileUploadId} is {received} bytes, more than the {max} bytes allowed. Create a new upload with a smaller file.
        FILE_CONTENT_MISMATCH: "The file uploaded for {fileUploadId} is not a valid {expected} file: its first bytes look like {detected}, not the content type you declared. Create a new upload with the correct contentType and file."
        DOCUMENT_ARCHIVE_BLOCKED: Version {version} of {documentType} cannot be archived or restored. {reason} GET /v2/installer/projects/{projectId}/documents shows each version and its state.
        PHOTO_CATEGORY_UNKNOWN: The photo category {category} does not exist. GET /v2/installer/projects/{projectId}/photos lists the categories for this project.
        MONITORING_ACCESS_INVALID: "The monitoring sites are not valid: {reason} Fix the sites listed in details and send the request again."
        MONITORING_SITE_DUPLICATE: "A monitoring site is already used on another project: {reason} Check the site ID with the monitoring provider."
        MONITORING_ACCESS_CHANGED: The monitoring sites changed since you read them. GET the monitoring access again, apply your change, and send it with the new baseSitesHash.
        MONITORING_ACCESS_LOCKED: The monitoring sites cannot change right now. {reason} Ask Participate Energy if a site must change.
        MONITORING_ACCESS_RATE_LIMITED: Too many monitoring site saves on this project. {reason} Wait, then retry.
        MONITORING_ACCESS_NOT_ALLOWED: Your company cannot change monitoring sites here. {reason} Ask Participate Energy for help.
        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.
        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/installer/webhooks first.
        SANDBOX_SCENARIO_INVALID: "The sandboxScenario {received} is not one of: {allowed}. Send one of the scenarios from GET /v2/installer/sandbox/scenarios, or leave it out for project_created."
        SANDBOX_DOCUMENT_TYPE_UNKNOWN: The documentType {documentType} is not a document slot of this project. Use a documentType from GET /v2/installer/projects/{projectId}/documents.
        SANDBOX_TRANSITION_INVALID: "The event {event} cannot be simulated on this project now: {reason}. Send an event that fits the project's current state."
        ADDRESS_PO_BOX: A site address cannot be a PO Box. Send the street address where the system is installed.
        AMOUNT_OUT_OF_RANGE: The {field} is an amount in US dollars, between {min} and {max}; {received} is outside that range. {hint}.
        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.
        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.
        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.
        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.
        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.
        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.
        SYSTEM_SIZE_MISMATCH: "The systemSizeKw {received} does not fit the modules: {basis}. Send the DC size in kW that matches the modules, or fix the module quantity."
        SYSTEM_TYPE_CHANGE_REQUIRES_CHANGE_ORDER: Adding a battery changes the system to Solar + Storage, which needs a change order. Contact PE at raceway.support@participate.energy.
        LENDER_NOT_APPROVED: The lender is not on the Participate Energy approved lender list for this project's state. details[0].approved lists the approved lenders; send one of those names, or null for no lender. To have a lender approved, contact Participate Energy at raceway.support@participate.energy.
        FILE_EMPTY: The file uploaded for {fileUploadId} is empty (0 bytes). Create a new upload and PUT the whole file.
        UPLOAD_FILE_EMPTY: The file for upload {uploadId} is empty (0 bytes). Create a new upload and PUT the signed customer agreement as a PDF; you can use the same externalId.
        DRAFT_NOT_FOUND: No contract draft {draftId} exists for this installer in this environment. List your drafts with GET /v2/installer/contract-drafts.
        DRAFT_NOT_READY: "Contract draft {draftId} is not ready to send: {count} issue(s). Fix each issue in details with PATCH /v2/installer/contract-drafts/{draftId}, then send again."
        DRAFT_ALREADY_SENT: Contract draft {draftId} was already sent, so it cannot be changed or deleted. Read the project's contract status, or void and re-send the contract.
        DRAFT_SEND_IN_PROGRESS: Contract draft {draftId} is being sent right now, so it cannot be changed. Read the draft again in a minute.
        DRAFT_PORTAL_SEND_UNCONFIRMED: The rep started sending contract draft {draftId} from the Installer Portal and it did not finish. Check the rep's Projects list for this customer before you send again. If no project was created, delete this draft and create a new one.
        DRAFT_STATE_INVALID: Contract draft {draftId} was changed outside the API and no longer points to a project your integration created from it, so it was not sent. Check the rep's Projects list for this customer before you create a new draft.
        ASSIGNEE_NOT_FOUND: The assignedToEmail is not an active user of this installer. Send the email of an active Installer Portal user of your organization, or leave it out to assign the draft to the X-PE-Actor-Email user.
        ASSIGNEE_NOT_PERMITTED: "The assigned user has the role {role}, which cannot {action}. Assign a user with one of these roles: {allowed}."
        PREFILL_LOCKED_FIELD: Your organization's prefill locks {field} to {lockedValue} for this state. Leave {field} out, or send the locked value. GET /v2/installer/contract-drafts/defaults?stateCode={stateCode} lists the locked fields.
        EQUIPMENT_NOT_ALLOWED_BY_PREFILL: Your organization's prefill does not allow {item} ({category}) in {stateCode}. Choose another item; GET /v2/installer/contract-drafts/defaults?stateCode={stateCode} lists the excluded items.
        DRAFT_FIELD_REQUIRED: A field the contract needs is missing. The issue names the field; send it with PATCH /v2/installer/contract-drafts/{draftId}.
        DRAFT_FIELD_INVALID: A field value is not in the form the contract needs (an email, a phone with 10 or 11 digits, or a ZIP code). The issue names the field.
        PAYMENTS_DO_NOT_SUM: The payments must add up to the Net Amount Due to the cent. Change the payment amounts so they match.
        PAYMENT_ONE_TOO_HIGH: Payment 1 (due at signing) may be at most the lower of $1,000 ($500 in New York and New Jersey) and 10% of the Net Amount Due. Lower Payment 1 and move the rest to a later payment.
        PAYMENT_EXCEEDS_NET_AMOUNT_DUE: A payment is larger than the Net Amount Due. Lower it.
        ADDITIONAL_PRODUCT_EXCEEDS_EPC: An additional product amount is larger than the EPC amount. Check the amount; it is in USD.
        PTO_BEFORE_INSTALL: The forecasted PTO date must be after the forecasted install start date. Send sales.ptoDate later than sales.installStartDate.
        INSTALL_BEFORE_CONTRACT: "The forecasted install start date cannot be before the contract date. Send sales.installStartDate on or after sales.contractDate."
        EQUIPMENT_NOT_FOR_SYSTEM_TYPE: "The equipment does not fit the system type: a Solar Only system has no battery. Send systemType PV+Storage, or leave the battery out."
        COSIGNER_NOT_SUPPORTED: "The customer agreement for this state has no place for a cosigner to sign. Remove the cosigner (cosigner: null), or ask Participate Energy to add a cosigner signature to the agreement."
        CONTRACT_DATA_MISSING: "The customer agreement needs a value that does not come from the draft (it is read from your organization's settings or Participate Energy's records). The issue names it. Ask Participate Energy at raceway.support@participate.energy."
        MILESTONE_NAME_INVALID: Each payment milestone name must be 5 to 30 characters. Rename the milestone the issue names.
        COSIGNER_EMAIL_SAME_AS_CUSTOMER: "The cosigner email must differ from the customer email: each signer gets their own signing link. Send the cosigner's own email."
        EQUIPMENT_MANUFACTURER_MISMATCH: "The inverter and battery manufacturers differ. Confirm the pairing with system.confirmManufacturerMismatch: true, or change the equipment."
        PRICING_NOT_CALCULATED: The lease price of the draft has not been calculated yet. The issue lists the pricing inputs to send.
        PRICING_STALE: A pricing input changed after the lease price was calculated (for example in the Installer Portal). Update the draft with PATCH so the price is calculated again.
        AUTO_SIGNER_REQUIRED: Nobody at your company is set up to sign the customer agreement automatically, so it cannot be sent. {reason} Ask your administrator to set up a default signer in E-sign Setup in the Installer Portal, then send again.
        CONTRACT_TEMPLATE_NOT_FOUND: There is no customer agreement ready for {stateCode} for your company yet, so the contract cannot be sent. Ask Participate Energy at raceway.support@participate.energy to publish one, then send again.
        CONTRACT_NOT_SENDABLE: "Participate Energy could not send the contract: {reason} Fix the cause, then send again. When details name a projectId, the project was created; send its contract with POST /v2/installer/projects/<projectId>/contract-esign/send."
        CONTRACT_SEND_FAILED: The contract for project {projectId} could not be sent because of an error at Participate Energy. The project exists. Retry the send in a few minutes with POST /v2/installer/projects/{projectId}/contract-esign/send.
        PACKET_NOT_FOUND: Project {projectId} has no contract sent for e-signature. Send one with POST /v2/installer/contract-drafts/<draftId>/send or POST /v2/installer/projects/{projectId}/contract-esign/send.
        PACKET_NOT_VOIDABLE: The contract for project {projectId} is {status}, so it cannot be voided. Read it with GET /v2/installer/projects/{projectId}/contract-esign.
        CONTRACT_ALREADY_SIGNED: "The contract for project {projectId} is signed (completed), so it is not sent again. Read it with GET /v2/installer/projects/{projectId}/contract-esign. A change to a signed contract needs a change order through Participate Energy."
        CONTRACT_ESIGN_MOVED: POST /v2/installer/contract-esign was replaced in 2.2. Send a contract draft with POST /v2/installer/contract-drafts/<draftId>/send, or send the contract of an existing project again with POST /v2/installer/projects/<projectId>/contract-esign/send.
        STATE_FIELDS_UNAVAILABLE: "The {stateCode} contract fields could not be read right now, so nothing was saved or checked. Retry the same request in a few minutes."
    UploadStatus:
      type: string
      enum:
        - awaiting_file
        - queued
        - processing
        - project_created
        - needs_attention
        - failed
      description: The status of a contract upload.
    UploadOutcome:
      type: string
      enum:
        - project_created
        - draft_failed_basic_tests
        - draft_invalid_document
        - draft_duplicate
        - draft_manual_entry
        - product_mismatch
        - canon_rejected
        - sibyl_error
        - cancelled
        - processing_failed
        - upload_expired
        - file_rejected
      description: The outcome of a contract upload. Null until the review ends.
      x-enum-descriptions:
        project_created: Participate Energy read the contract and created the project. Read it with GET /v2/installer/projects/{projectId} and follow its Actions and approvals.
        draft_failed_basic_tests: The contract was read, but it did not pass the basic checks, so it was saved as a draft in the Installer Portal and no project was created. The failed checks are in errors. Fix them in the Installer Portal draft, or upload a corrected contract.
        draft_invalid_document: The file does not look like a Participate Energy customer agreement, so no project was created. Upload the signed Participate Energy customer agreement.
        draft_duplicate: The contract matches a project that already exists for this installer, so it was saved as a draft in the Installer Portal and no project was created. If it is a new project, create it from the draft in the Installer Portal.
        draft_manual_entry: The contract could not be read automatically, so it was saved as a draft in the Installer Portal. Enter the missing details there to create the project.
        product_mismatch: The contract is for a different Participate Energy product than the productType of the upload, so no project was created. Create a new upload with the right productType.
        canon_rejected: The contract was read, but its data did not pass Participate Energy's project checks, so no project was created. Review the upload in the Installer Portal, or contact raceway.support@participate.energy with the uploadId.
        sibyl_error: Participate Energy could not finish reading the contract because of a processing error, so no project was created. Create a new upload, or retry the upload in the Installer Portal.
        cancelled: The upload was cancelled before a project was created. Create a new upload if the contract should still become a project.
        processing_failed: Participate Energy did not finish processing the contract, so no project was created and the externalId was released. Create a new upload to try again; you can use the same externalId. If it fails again, contact raceway.support@participate.energy with the uploadId {uploadId}.
        upload_expired: The upload URL expired before a file arrived, so the upload was closed and its externalId was released. Create a new upload with POST /v2/installer/contract-uploads.
        file_rejected: The uploaded file was not a PDF or was larger than 25 MB, so the upload was closed and its externalId was released. Create a new upload for the signed customer agreement as a PDF.
    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: A Test contract upload scenario. Default project_created.
    SimulateEvent:
      type: string
      enum:
        - document_approved
        - document_rejected
        - action_raised
        - photos_approved
        - ic_approved
        - pc_approved
        - project_cancelled
        - contract_viewed
        - contract_signed
        - contract_declined
        - contract_voided
        - contract_expired
      description: A simulated PE event on a Test project.
    WebhookEventType:
      type: string
      enum:
        - project.ic_approved
        - project.pc_approved
        - project.action_created
        - project.contract_status_changed
        - webhook.test
      description: A webhook event type.
    ProjectStatus:
      type: string
      enum:
        - Active
        - At-risk
        - Not Submitted
        - Pending Cancellation
        - DQ
        - Cancelled
        - Cancelled-Duplicate
        - Completed
        - On Hold
      description: The project status.
    Milestone:
      type: string
      enum:
        - Project Onboarded
        - Inspection Complete
        - Project Complete
        - Closed
        - Cancellation In Progress
      description: The project milestone. PE sets it from the documents and the approvals.
    ActionStatus:
      type: string
      enum:
        - open
        - resolved
        - reject
        - ai_error
        - cannot_resolve
      description: The status of an Action.
    EquipmentCategory:
      type: string
      enum:
        - acModule
        - module
        - inverter
        - racking
        - battery
        - batteryExpansion
      description: A project equipment category. acModule is an AC module (a module with a built-in inverter).
    MonitoringProvider:
      type: string
      enum:
        - tesla
        - enphase
        - solaredge
        - lunar
        - qcells
        - other
      description: A monitoring provider.
    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 key 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: The field with the problem, as a dotted path (for example customer.email, or query.limit). Empty when no field applies.
        issue:
          type: string
          description: What is wrong with the field.
        expected:
          type: string
          description: What PE expected.
        received:
          description: "What PE received: the type, or the value for numbers, booleans and enum values."
      description: One problem. Some codes add more keys, for example suggestions and candidates on the equipment codes, or limit, window and resetAt on the limit codes.
    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. The text can change; act on code."
        retryable:
          type: boolean
          description: Whether the same request can succeed later without changes.
        details:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetail"
          description: The fields with problems. Empty when no field applies.
        docsUrl:
          type: string
          description: A link to this code in the documentation.
          format: uri
    ContractDraftStatus:
      type: string
      enum:
        - draft
        - sending
        - sent
        - sent_create_only
      description: draft until it is sent.
    ContractDraftRequest:
      type: object
      additionalProperties: false
      description: A contract draft body. Every field is optional except siteAddress.stateCode.
      properties:
        assignedToEmail:
          type: string
          description: "The rep who owns the draft: an active Installer Portal user of your company (administrator, editor or operations). Default: the X-PE-Actor-Email user."
        externalId:
          type:
            - string
            - "null"
          description: Your id for the deal. Letters, digits, - and _, at most 128.
        label:
          type: string
          description: The name in the Drafts tab. At most 200 characters.
        customer:
          type: object
          additionalProperties: false
          properties:
            firstName:
              type: string
              description: At most 100 characters, on one line (no control characters).
            lastName:
              type: string
              description: At most 100 characters, on one line (no control characters).
            email:
              type: string
              description: An email.
            phone:
              type: string
              description: 10 digits, or 11 digits starting with 1.
        cosigner:
          type:
            - object
            - "null"
          additionalProperties: false
          properties:
            firstName:
              type: string
              description: At most 100 characters, on one line (no control characters).
            lastName:
              type: string
              description: At most 100 characters, on one line (no control characters).
            email:
              type: string
              description: An email.
            phone:
              type: string
              description: 10 digits, or 11 digits starting with 1.
          description: The optional second homeowner. null removes it. The state's agreement must have a cosigner signature (issue COSIGNER_NOT_SUPPORTED otherwise).
        siteAddress:
          type: object
          additionalProperties: false
          description: The site.
          required:
            - stateCode
          properties:
            street:
              type: string
              description: No PO Box.
            unit:
              type: string
              description: Unit or apartment.
            city:
              type: string
              description: City.
            stateCode:
              type: string
              description: 2-letter US state code.
            zipCode:
              type: string
              description: 5 digits or ZIP+4, not 00000.
            county:
              type: string
              description: County.
        mailingAddress:
          type:
            - object
            - "null"
          additionalProperties: false
          properties:
            street:
              type: string
              description: Street (a PO Box is allowed).
            city:
              type: string
              description: City.
            stateCode:
              type: string
              description: 2-letter US state code.
            zipCode:
              type: string
              description: 5 digits or ZIP+4.
          description: "Only when it differs from the site. null: same as the site."
        utility:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
              description: A utility of the state, as GET /utilities lists it.
            nameOnBill:
              type:
                - string
                - "null"
              description: The name on the utility bill when it is not the customer's.
        product:
          type: object
          additionalProperties: false
          properties:
            productType:
              type: string
              description: Synthetic Cash (default). Distributed Microgrid is refused.
              enum:
                - Synthetic Cash
                - Distributed Microgrid
        system:
          type: object
          additionalProperties: false
          properties:
            systemType:
              type: string
              description: Solar Only, PV+Storage or Storage Only (solar_only, solar_battery, battery_only also work).
            systemSizeKw:
              type: number
              description: "Optional check, kW DC from 0.5 to 250: within 25% of modules x watts / 1000 (exactly 25% is accepted). The draft's PV size is always modules x watts / 1000, which the builder takes from 1.2 to 50 kW DC by default (issue SYSTEM_SIZE_OUT_OF_RANGE)."
            existingSolarOnProperty:
              type: boolean
            annualUsageKwh:
              type: number
              description: The customer's annual usage, kWh.
            annualProductionKwh:
              type: number
              description: Estimated year 1 production, kWh.
            energySavingsCalculator:
              type: string
              description: Aurora, Energy Toolbase, Solargraf, OpenSolar, Solo, Artemis, Enerflo or Subcontractor Hub.
            energyCommunity:
              description: "true, false, or \"auto\" (default: PE runs the Energy Community check)."
              oneOf:
                - type: boolean
                - type: string
                  enum:
                    - auto
            confirmManufacturerMismatch:
              type: boolean
              description: Confirms an inverter and a battery from different manufacturers.
        equipment:
          type: array
          maxItems: 5
          description: One line per category.
          items:
            type: object
            additionalProperties: false
            required:
              - category
            properties:
              category:
                type: string
                description: module, acModule, inverter, racking or battery.
                enum:
                  - module
                  - acModule
                  - inverter
                  - racking
                  - battery
              avlItemId:
                type: string
                description: An AVL item id (send this or name).
              name:
                type: string
                description: An equipment string (send this or avlItemId).
              quantity:
                type: integer
                description: Units (module and inverter at most 100, battery at most 10).
              wattsDc:
                type: number
                description: "Module DC watts per module. Needed when the AVL item has no wattage; when it has one, leave it out or send the same wattage (another value is VALIDATION_FAILED)."
              acWatts:
                type: number
                description: "Inverter AC watts per unit (default: the AVL value)."
              outputPowerW:
                type: number
                description: Battery output power in W (Storage Only).
        financials:
          type: object
          additionalProperties: false
          properties:
            epcAmount:
              type: number
              description: The total EPC, USD, 1,000 to 500,000, at most 2 decimals.
            dcBonusRecipient:
              type: string
              description: installer or customer (any case).
            lender:
              type:
                - object
                - "null"
              additionalProperties: false
              required:
                - financed
              properties:
                financed:
                  type: boolean
                name:
                  type: string
                  description: The lender, needed when financed is true. A name not on PE's list is saved as Other.
            paymentInstructions:
              type: string
              description: At most 2000 characters.
            addersAndUpgrades:
              type: string
              description: At most 100 characters.
            additionalProducts:
              type: array
              maxItems: 5
              description: The complete list of selected products.
              items:
                type: object
                additionalProperties: false
                required:
                  - slug
                  - amount
                properties:
                  slug:
                    type: string
                    description: full-reroof, partial-reroof, solar-insure, extended-warranty or ev-charger.
                  amount:
                    type: number
                    description: USD, at most 2 decimals.
                  coveragePercent:
                    type: number
                    description: "full-reroof only: 5 to 85, the share of the roof under the array."
            includedIncentives:
              type: array
              maxItems: 2
              items:
                type: object
                additionalProperties: false
                required:
                  - id
                properties:
                  id:
                    type: string
                    description: An included incentive id (GET /contract-drafts/defaults).
                  amount:
                    type: number
                    description: USD, at most 2 decimals; 0 allowed.
            incentives:
              type: array
              maxItems: 4
              items:
                type: object
                additionalProperties: false
                required:
                  - id
                  - amount
                properties:
                  id:
                    type: string
                    description: An additional incentive id.
                  amount:
                    type: number
                    description: USD, at most 2 decimals.
            payments:
              type: array
              maxItems: 4
              description: "Payment 1 is always Deposit/Due at signing: leave its name out."
              items:
                type: object
                additionalProperties: false
                required:
                  - amount
                properties:
                  name:
                    type: string
                    description: Milestone name, 5 to 30 characters (payments 2 to 4).
                  amount:
                    type: number
                    description: USD, at most 2 decimals.
        sales:
          type: object
          additionalProperties: false
          properties:
            salesRepName:
              type: string
              description: Name.
            salesRepEmail:
              type: string
              description: Email.
            salesRepPhone:
              type: string
              description: Phone.
            salesRepLicense:
              type: string
              description: License number.
            nyLicenseNumber:
              type: string
              description: New York local license number.
            contractDate:
              type: string
              description: YYYY-MM-DD, default today.
            installStartDate:
              type: string
              description: Forecasted install start, YYYY-MM-DD, on or after the contract date.
            ptoDate:
              type: string
              description: Forecasted PTO, YYYY-MM-DD.
        stateFields:
          type: object
          description: The state's contract fields by key (GET /contract-drafts/defaults lists them with min, max and required; a number or currency field without its own min takes 0 or more). null clears one.
          additionalProperties:
            type:
              - string
              - number
              - boolean
              - "null"
    ContractDraftPatchRequest:
      type: object
      additionalProperties: false
      description: "A change: objects merge, lists replace, null clears."
      properties:
        assignedToEmail:
          type: string
          description: "The rep who owns the draft: an active Installer Portal user of your company (administrator, editor or operations). Default: the X-PE-Actor-Email user."
        externalId:
          type:
            - string
            - "null"
          description: Your id for the deal. Letters, digits, - and _, at most 128.
        label:
          type: string
          description: The name in the Drafts tab. At most 200 characters.
        customer:
          type: object
          additionalProperties: false
          properties:
            firstName:
              type: string
              description: At most 100 characters, on one line (no control characters).
            lastName:
              type: string
              description: At most 100 characters, on one line (no control characters).
            email:
              type: string
              description: An email.
            phone:
              type: string
              description: 10 digits, or 11 digits starting with 1.
        cosigner:
          type:
            - object
            - "null"
          additionalProperties: false
          properties:
            firstName:
              type: string
              description: At most 100 characters, on one line (no control characters).
            lastName:
              type: string
              description: At most 100 characters, on one line (no control characters).
            email:
              type: string
              description: An email.
            phone:
              type: string
              description: 10 digits, or 11 digits starting with 1.
          description: The optional second homeowner. null removes it. The state's agreement must have a cosigner signature (issue COSIGNER_NOT_SUPPORTED otherwise).
        siteAddress:
          type: object
          additionalProperties: false
          description: The site.
          properties:
            street:
              type: string
              description: No PO Box.
            unit:
              type: string
              description: Unit or apartment.
            city:
              type: string
              description: City.
            stateCode:
              type: string
              description: 2-letter US state code.
            zipCode:
              type: string
              description: 5 digits or ZIP+4, not 00000.
            county:
              type: string
              description: County.
        mailingAddress:
          type:
            - object
            - "null"
          additionalProperties: false
          properties:
            street:
              type: string
              description: Street (a PO Box is allowed).
            city:
              type: string
              description: City.
            stateCode:
              type: string
              description: 2-letter US state code.
            zipCode:
              type: string
              description: 5 digits or ZIP+4.
          description: "Only when it differs from the site. null: same as the site."
        utility:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
              description: A utility of the state, as GET /utilities lists it.
            nameOnBill:
              type:
                - string
                - "null"
              description: The name on the utility bill when it is not the customer's.
        product:
          type: object
          additionalProperties: false
          properties:
            productType:
              type: string
              description: Synthetic Cash (default). Distributed Microgrid is refused.
              enum:
                - Synthetic Cash
                - Distributed Microgrid
        system:
          type: object
          additionalProperties: false
          properties:
            systemType:
              type: string
              description: Solar Only, PV+Storage or Storage Only (solar_only, solar_battery, battery_only also work).
            systemSizeKw:
              type: number
              description: "Optional check, kW DC from 0.5 to 250: within 25% of modules x watts / 1000 (exactly 25% is accepted). The draft's PV size is always modules x watts / 1000, which the builder takes from 1.2 to 50 kW DC by default (issue SYSTEM_SIZE_OUT_OF_RANGE)."
            existingSolarOnProperty:
              type: boolean
            annualUsageKwh:
              type: number
              description: The customer's annual usage, kWh.
            annualProductionKwh:
              type: number
              description: Estimated year 1 production, kWh.
            energySavingsCalculator:
              type: string
              description: Aurora, Energy Toolbase, Solargraf, OpenSolar, Solo, Artemis, Enerflo or Subcontractor Hub.
            energyCommunity:
              description: "true, false, or \"auto\" (default: PE runs the Energy Community check)."
              oneOf:
                - type: boolean
                - type: string
                  enum:
                    - auto
            confirmManufacturerMismatch:
              type: boolean
              description: Confirms an inverter and a battery from different manufacturers.
        equipment:
          type: array
          maxItems: 5
          description: One line per category.
          items:
            type: object
            additionalProperties: false
            required:
              - category
            properties:
              category:
                type: string
                description: module, acModule, inverter, racking or battery.
                enum:
                  - module
                  - acModule
                  - inverter
                  - racking
                  - battery
              avlItemId:
                type: string
                description: An AVL item id (send this or name).
              name:
                type: string
                description: An equipment string (send this or avlItemId).
              quantity:
                type: integer
                description: Units (module and inverter at most 100, battery at most 10).
              wattsDc:
                type: number
                description: "Module DC watts per module. Needed when the AVL item has no wattage; when it has one, leave it out or send the same wattage (another value is VALIDATION_FAILED)."
              acWatts:
                type: number
                description: "Inverter AC watts per unit (default: the AVL value)."
              outputPowerW:
                type: number
                description: Battery output power in W (Storage Only).
        financials:
          type: object
          additionalProperties: false
          properties:
            epcAmount:
              type: number
              description: The total EPC, USD, 1,000 to 500,000, at most 2 decimals.
            dcBonusRecipient:
              type: string
              description: installer or customer (any case).
            lender:
              type:
                - object
                - "null"
              additionalProperties: false
              required:
                - financed
              properties:
                financed:
                  type: boolean
                name:
                  type: string
                  description: The lender, needed when financed is true. A name not on PE's list is saved as Other.
            paymentInstructions:
              type: string
              description: At most 2000 characters.
            addersAndUpgrades:
              type: string
              description: At most 100 characters.
            additionalProducts:
              type: array
              maxItems: 5
              description: The complete list of selected products.
              items:
                type: object
                additionalProperties: false
                required:
                  - slug
                  - amount
                properties:
                  slug:
                    type: string
                    description: full-reroof, partial-reroof, solar-insure, extended-warranty or ev-charger.
                  amount:
                    type: number
                    description: USD, at most 2 decimals.
                  coveragePercent:
                    type: number
                    description: "full-reroof only: 5 to 85, the share of the roof under the array."
            includedIncentives:
              type: array
              maxItems: 2
              items:
                type: object
                additionalProperties: false
                required:
                  - id
                properties:
                  id:
                    type: string
                    description: An included incentive id (GET /contract-drafts/defaults).
                  amount:
                    type: number
                    description: USD, at most 2 decimals; 0 allowed.
            incentives:
              type: array
              maxItems: 4
              items:
                type: object
                additionalProperties: false
                required:
                  - id
                  - amount
                properties:
                  id:
                    type: string
                    description: An additional incentive id.
                  amount:
                    type: number
                    description: USD, at most 2 decimals.
            payments:
              type: array
              maxItems: 4
              description: "Payment 1 is always Deposit/Due at signing: leave its name out."
              items:
                type: object
                additionalProperties: false
                required:
                  - amount
                properties:
                  name:
                    type: string
                    description: Milestone name, 5 to 30 characters (payments 2 to 4).
                  amount:
                    type: number
                    description: USD, at most 2 decimals.
        sales:
          type: object
          additionalProperties: false
          properties:
            salesRepName:
              type: string
              description: Name.
            salesRepEmail:
              type: string
              description: Email.
            salesRepPhone:
              type: string
              description: Phone.
            salesRepLicense:
              type: string
              description: License number.
            nyLicenseNumber:
              type: string
              description: New York local license number.
            contractDate:
              type: string
              description: YYYY-MM-DD, default today.
            installStartDate:
              type: string
              description: Forecasted install start, YYYY-MM-DD, on or after the contract date.
            ptoDate:
              type: string
              description: Forecasted PTO, YYYY-MM-DD.
        stateFields:
          type: object
          description: The state's contract fields by key (GET /contract-drafts/defaults lists them with min, max and required; a number or currency field without its own min takes 0 or more). null clears one.
          additionalProperties:
            type:
              - string
              - number
              - boolean
              - "null"
    ContractDraftIssue:
      type: object
      additionalProperties: false
      required:
        - step
        - field
        - code
        - message
        - severity
      properties:
        step:
          type: string
          description: The builder step.
        field:
          type: string
          description: The body field (empty for CONTRACT_DATA_MISSING and the agreement's own issues).
        code:
          $ref: "#/components/schemas/ErrorCode"
        message:
          type: string
          description: What to fix.
        severity:
          type: string
          description: error or warning.
          enum:
            - error
            - warning
        incentiveId:
          type: string
          description: The included incentive an amount issue is about.
    ContractDraftValidation:
      type: object
      additionalProperties: false
      required:
        - readyToSend
        - issues
      properties:
        readyToSend:
          type: boolean
        issues:
          type: array
          items:
            $ref: "#/components/schemas/ContractDraftIssue"
    ContractDraft:
      type: object
      additionalProperties: false
      required:
        - draftId
        - status
        - assignedTo
        - externalId
        - label
        - stateCode
        - productType
        - createdAt
        - updatedAt
        - body
        - prefilledFields
        - pricing
        - validation
        - warnings
        - portalUrl
        - projectId
        - packetId
        - sentVia
      properties:
        draftId:
          type:
            - string
            - "null"
          description: cdr_... (null on a dry run).
        status:
          $ref: "#/components/schemas/ContractDraftStatus"
        assignedTo:
          type: object
          additionalProperties: false
          properties:
            email:
              type: string
              description: The rep's email.
            name:
              type:
                - string
                - "null"
        externalId:
          type:
            - string
            - "null"
        label:
          type: string
          description: The Drafts tab name.
        stateCode:
          type: string
          description: The site state.
        productType:
          type: string
          description: Synthetic Cash.
        createdAt:
          type:
            - string
            - "null"
          format: date-time
        updatedAt:
          type:
            - string
            - "null"
          format: date-time
        body:
          $ref: "#/components/schemas/ContractDraftRequest"
        prefilledFields:
          type: array
          items:
            type: string
          description: Body fields that hold a value from your prefill.
        pricing:
          type:
            - object
            - "null"
          description: The /pricing/lease response for the draft, or null when it could not be calculated.
          additionalProperties: true
        validation:
          $ref: "#/components/schemas/ContractDraftValidation"
        warnings:
          type: array
          items:
            type: object
            additionalProperties: true
          description: "Pricing warnings, and PREFILL_INCENTIVE_NOT_APPLICABLE (a prefill incentive that the draft's state, system type, utility or contract date does not offer; it has code, field, incentiveId, reason and message). reason not_offered_in_state or wrong_incentive_list is a prefill error; system_type, utility and contract_date are expected for a correct prefill. A warning never stops the draft."
        portalUrl:
          type:
            - string
            - "null"
          description: Opens the draft in the Contract Builder (production keys only).
        projectId:
          type:
            - string
            - "null"
          description: Set once the draft is sent.
        packetId:
          type:
            - string
            - "null"
          description: Set once the draft is sent through the API. A draft the rep sent from the portal has `packetId` null; read its contract with `GET /projects/{projectId}/contract-esign`.
        sentVia:
          type:
            - string
            - "null"
          enum:
            - api
            - portal
            - null
          description: How the draft was sent, once it is `sent` or `sent_create_only`; null before. `portal` when the rep sent it from the Contract Builder.
        dryRun:
          type: boolean
          description: On create only.
    ContractDraftResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractDraft"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractDraftList:
      type: object
      additionalProperties: false
      required:
        - drafts
        - nextCursor
      properties:
        drafts:
          type: array
          items:
            $ref: "#/components/schemas/ContractDraft"
        nextCursor:
          type:
            - string
            - "null"
    ContractDraftListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractDraftList"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractDraftDefaults:
      type: object
      additionalProperties: true
      description: "Your prefill for a state: defaults, locks, equipmentLimits (one {name, avlItemId} row per AVL item id an excluded name covers), includedIncentivesForState, stateFields (key, label, type, required, requiredForSystemTypes: the system types a required field is asked for, null for all; options, min, max, zeroAllowed: whether a 0 counts as a value, null when not a number; source), stateSpecificFields (the body fields outside stateFields that only this state has, each {field, label, type, required}) and contractTemplate: the state's customer agreement, {available, cosignerAllowed, requiredFields: [{field, label, onlyWithCosigner?, anyOf?}], issue}, null when PE could not read it; available false with issue {code, message} when no contract can be sent."
    ContractDraftDefaultsResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractDraftDefaults"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractDraftValidateResult:
      type: object
      additionalProperties: false
      required:
        - draftId
        - status
        - validation
      properties:
        draftId:
          type: string
          description: The draft.
        status:
          $ref: "#/components/schemas/ContractDraftStatus"
        validation:
          $ref: "#/components/schemas/ContractDraftValidation"
    ContractDraftValidateResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractDraftValidateResult"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractDraftDeleteResult:
      type: object
      additionalProperties: false
      required:
        - draftId
        - deleted
      properties:
        draftId:
          type: string
          description: The draft.
        deleted:
          type: boolean
    ContractDraftDeleteResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractDraftDeleteResult"
        meta:
          $ref: "#/components/schemas/Meta"
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
        - meta
      properties:
        error:
          $ref: "#/components/schemas/Error"
        meta:
          $ref: "#/components/schemas/Meta"
    Installer:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          description: Your company name in PE's records.
    RateLimits:
      type: object
      additionalProperties: false
      required:
        - readsPerMinute
        - writesPerMinute
        - pricingPerMinute
        - uploadsPerMinute
        - contractUploadsPerDay
        - fileUploadsPerDay
      properties:
        readsPerMinute:
          type: integer
          description: Read calls per minute for this key.
        writesPerMinute:
          type: integer
          description: Write calls per minute for this key.
        pricingPerMinute:
          type: integer
          description: Pricing calls per minute for this key.
        uploadsPerMinute:
          type: integer
          description: Upload create calls per minute for this key.
        contractUploadsPerDay:
          type: integer
          description: Contract uploads per UTC day for your company in this environment.
        fileUploadsPerDay:
          type: integer
          description: Document and photo files per UTC day for your company in this environment.
    Ping:
      type: object
      additionalProperties: false
      required:
        - ok
        - environment
        - installer
        - grantId
        - keyPrefix
        - scopes
        - serverTime
      properties:
        ok:
          type: boolean
          const: true
        environment:
          $ref: "#/components/schemas/Environment"
        installer:
          $ref: "#/components/schemas/Installer"
        grantId:
          type: string
          description: The public id of the key (igr_...).
        keyPrefix:
          type: string
          description: The first characters of the key, for your logs.
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
        serverTime:
          type: string
          description: PE's clock.
          format: date-time
    StateRef:
      type: object
      additionalProperties: false
      required:
        - stateCode
        - name
      properties:
        stateCode:
          type: string
          description: 2-letter state code.
        name:
          type: string
          description: State name.
    Me:
      type: object
      additionalProperties: false
      required:
        - installer
        - environment
        - grantId
        - keyPrefix
        - scopes
        - activeStates
        - productTypes
        - apiContractUploadProducts
        - sungage
        - environments
        - rateLimits
      properties:
        installer:
          $ref: "#/components/schemas/Installer"
        environment:
          $ref: "#/components/schemas/Environment"
        grantId:
          type: string
          description: The public id of the key.
        keyPrefix:
          type: string
          description: The first characters of the key.
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
        activeStates:
          type: array
          items:
            $ref: "#/components/schemas/StateRef"
          description: The states where your company is active and PE operates.
        productTypes:
          type: array
          items:
            type: string
          description: The PE products enabled for your company, for example Synthetic Cash.
        apiContractUploadProducts:
          type: array
          items:
            type: string
          description: "The products a contract upload through this API can create for your company: the enabled ones among Synthetic Cash. Empty when your company has only Distributed Microgrid."
        sungage:
          type: object
          additionalProperties: false
          required:
            - enrolled
          properties:
            enrolled:
              type: boolean
              description: Whether the Sungage endpoints work for this key. Always true for a Test key.
        environments:
          type: object
          additionalProperties: false
          required:
            - test
            - live
          properties:
            test:
              type: boolean
              description: The Test environment is enabled.
            live:
              type: boolean
              description: Production is enabled.
        rateLimits:
          $ref: "#/components/schemas/RateLimits"
    AvlItem:
      type: object
      additionalProperties: false
      required:
        - avlItemId
        - sku
        - category
        - manufacturer
        - model
        - description
        - domesticContent
      properties:
        avlItemId:
          type: string
          description: The AVL item id. Use it in PUT /projects/{projectId}/equipment.
        sku:
          type: string
          description: The SKU.
        category:
          $ref: "#/components/schemas/AvlCategory"
        manufacturer:
          type: string
        model:
          type:
            - string
            - "null"
        description:
          type:
            - string
            - "null"
          description: The AVL display string (the dropdown reference). This is the exact name to use for equipment by name.
        domesticContent:
          $ref: "#/components/schemas/DomesticContentValues"
    AvlVersion:
      type: object
      additionalProperties: false
      required:
        - number
        - label
        - uploadedAt
      properties:
        number:
          type:
            - integer
            - "null"
          description: The AVL version number.
        label:
          type:
            - string
            - "null"
          description: The version label.
        uploadedAt:
          type:
            - string
            - "null"
          description: When PE published the version.
          format: date-time
    AvlPage:
      type: object
      additionalProperties: false
      required:
        - avlVersion
        - total
        - items
        - nextCursor
      properties:
        avlVersion:
          oneOf:
            - $ref: "#/components/schemas/AvlVersion"
            - type: "null"
          description: The current AVL version, or null when no version is active.
        unchangedSince:
          type: boolean
          description: "Only when you send updatedSince: true when the current AVL version is not newer than updatedSince. The page is then empty."
        updatedSinceApplied:
          type: boolean
          description: "Only when you send updatedSince: false when PE does not know when the current version became active. PE then returns the full list."
        total:
          type: integer
          description: The number of items that match the filters.
        items:
          type: array
          items:
            $ref: "#/components/schemas/AvlItem"
        nextCursor:
          type:
            - string
            - "null"
          description: Send it as cursor for the next page. Null on the last page.
    SafeHarborOpportunitySummary:
      type: object
      additionalProperties: false
      required:
        - opportunityId
        - name
        - programCode
        - strategy
        - status
        - bocDate
        - unitCost
        - unitsTotal
        - unitsConsumed
        - unitsAvailable
        - usableForPricing
      properties:
        opportunityId:
          type: string
          description: The opportunity id (SHOID).
        name:
          type: string
          description: The program name.
        programCode:
          type:
            - string
            - "null"
        strategy:
          type: string
          description: The Safe Harbor strategy.
        status:
          type: string
          description: The opportunity status.
        bocDate:
          type:
            - string
            - "null"
          description: The beginning of construction date. It sets the Domestic Content year.
          format: date
        unitCost:
          type:
            - number
            - "null"
          description: The deduction per unit, in USD.
        unitsTotal:
          type:
            - integer
            - "null"
        unitsConsumed:
          type:
            - integer
            - "null"
        unitsAvailable:
          type:
            - integer
            - "null"
        usableForPricing:
          type: boolean
          description: Whether pricing can take a Safe Harbor deduction from this opportunity.
    SafeHarborOpportunityList:
      type: object
      additionalProperties: false
      required:
        - opportunities
      properties:
        opportunities:
          type: array
          items:
            $ref: "#/components/schemas/SafeHarborOpportunitySummary"
    SafeHarborOpportunityDetail:
      type: object
      additionalProperties: false
      required:
        - opportunityId
        - name
        - programCode
        - strategy
        - status
        - bocDate
        - unitCost
        - unitsTotal
        - unitsConsumed
        - unitsAvailable
        - usableForPricing
        - customAvl
      properties:
        opportunityId:
          type: string
          description: The opportunity id (SHOID).
        name:
          type: string
          description: The program name.
        programCode:
          type:
            - string
            - "null"
        strategy:
          type: string
          description: The Safe Harbor strategy.
        status:
          type: string
          description: The opportunity status.
        bocDate:
          type:
            - string
            - "null"
          description: The beginning of construction date. It sets the Domestic Content year.
          format: date
        unitCost:
          type:
            - number
            - "null"
          description: The deduction per unit, in USD.
        unitsTotal:
          type:
            - integer
            - "null"
        unitsConsumed:
          type:
            - integer
            - "null"
        unitsAvailable:
          type:
            - integer
            - "null"
        usableForPricing:
          type: boolean
          description: Whether pricing can take a Safe Harbor deduction from this opportunity.
        customAvl:
          type: array
          items:
            $ref: "#/components/schemas/CustomAvlItem"
          description: The opportunity's active custom AVL. PE manages it.
    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:
              - name
              - primary
            properties:
              name:
                type: string
                description: The utility name. Use it as utility.name.
              primary:
                type: boolean
                description: True for the main utility of the ZIP code.
    StateList:
      type: object
      additionalProperties: false
      required:
        - states
        - enabledProducts
      properties:
        states:
          type: array
          items:
            $ref: "#/components/schemas/StateRef"
          description: The states where your company is active and PE operates.
        enabledProducts:
          type: array
          items:
            type: string
          description: The PE products enabled for your company.
    EquipmentMapEntry:
      type: object
      additionalProperties: false
      required:
        - rawValue
        - field
        - category
        - status
        - certified
        - certifiedAt
        - resolves
        - avlItem
        - suggestedAvlItem
        - matchCount
        - lastSeenAt
      properties:
        rawValue:
          type: string
          description: The equipment string as your company wrote it.
        field:
          type: string
          enum:
            - moduleSku
            - inverterSku
            - rackingPartNumber
            - storageLeadUnitPartNumber
            - storageExpansionUnitPartNumber
            - pvComboModInverter
          description: The equipment field the string was used in.
        category:
          type: string
          description: The AVL category.
        status:
          type: string
          description: The mapping status.
        certified:
          type: boolean
          description: PE certified the mapping.
        certifiedAt:
          type:
            - string
            - "null"
        resolves:
          type: boolean
          description: The string resolves to an AVL item.
        avlItem:
          oneOf:
            - $ref: "#/components/schemas/AvlItem"
            - type: "null"
          description: The AVL item the string resolves to.
        suggestedAvlItem:
          oneOf:
            - $ref: "#/components/schemas/AvlItem"
            - type: "null"
          description: A suggested AVL item when the string does not resolve.
        matchCount:
          type: integer
          description: How many times PE has seen the string.
        lastSeenAt:
          type:
            - string
            - "null"
    EquipmentMapPage:
      type: object
      additionalProperties: false
      required:
        - entries
        - nextCursor
        - truncated
      properties:
        entries:
          type: array
          items:
            $ref: "#/components/schemas/EquipmentMapEntry"
        nextCursor:
          type:
            - string
            - "null"
        truncated:
          type: boolean
          description: True when your map has more than 5000 entries and PE read only the first 5000.
    Reference:
      type: object
      additionalProperties: true
      required:
        - insuranceOptions
        - systemTypes
        - homeTypes
        - productTypes
        - documentTypes
        - photos
        - milestones
        - projectStatuses
        - actionStatuses
      description: PE's reference lists, with plain descriptions.
      properties:
        insuranceOptions:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - option
              - projectValue
              - label
              - description
              - riskAdjustmentRate
            properties:
              option:
                type: integer
              projectValue:
                type: string
                description: The value on a project (financials.insuranceOption).
              label:
                type: string
              description:
                type: string
              riskAdjustmentRate:
                type: number
                description: The share of the EPC added to the basis and taken from the IC payment.
        systemTypes:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - value
              - projectValue
              - label
              - description
            properties:
              value:
                type: string
                description: The API value.
              projectValue:
                type: string
                description: The value on a project (system.type).
              label:
                type: string
              description:
                type: string
        homeTypes:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - value
              - label
              - description
            properties:
              value:
                type: string
              label:
                type: string
              description:
                type: string
        productTypes:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - value
              - label
              - description
            properties:
              value:
                type: string
              label:
                type: string
              description:
                type: string
        documentTypes:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - documentType
              - label
              - category
              - stage
              - stageLabel
              - required
              - blocksReview
              - whenRequired
              - uploadVia
            properties:
              documentType:
                type: string
                description: The document type key used in document paths.
              label:
                type: string
              category:
                type: string
              stage:
                type: string
                enum:
                  - ic
                  - pc
                description: The approval that locks the slot.
              stageLabel:
                type: string
              required:
                type: boolean
              blocksReview:
                type: boolean
              whenRequired:
                type: string
                description: When PE requires the document, in plain words.
              uploadVia:
                type: string
                enum:
                  - documents
                  - photos
                  - monitoringAccess
                description: The endpoint group that uploads it.
        photos:
          type: object
          additionalProperties: true
          description: Photo rules and the categories by system type.
        milestones:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - value
              - description
            properties:
              value:
                $ref: "#/components/schemas/Milestone"
              description:
                type: string
        projectStatuses:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - value
              - description
            properties:
              value:
                $ref: "#/components/schemas/ProjectStatus"
              description:
                type: string
        actionStatuses:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - value
              - label
              - meaning
            properties:
              value:
                $ref: "#/components/schemas/ActionStatus"
              label:
                type: string
              meaning:
                type: string
    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 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. 1,000 to 500,000 USD (v2.2; outside it AMOUNT_OUT_OF_RANGE). 0 counts as left out (the rate only, no amount).
          minimum: 0
          maximum: 10000000
    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"
    CreateContractUploadRequest:
      type: object
      additionalProperties: false
      required:
        - stateCode
        - fileName
      properties:
        stateCode:
          type: string
          description: The 2-letter state of the site.
          pattern: ^[A-Za-z]{2}$
        productType:
          type: string
          enum:
            - Synthetic Cash
            - Distributed Microgrid
          description: "Default: Synthetic Cash. The API creates Synthetic Cash projects only: Distributed Microgrid returns PRODUCT_NOT_SUPPORTED_BY_API."
        externalId:
          type: string
          description: "Your id for the project: letters, digits, - and _. Spaces around it are trimmed."
          minLength: 1
          maxLength: 128
          pattern: ^[A-Za-z0-9_-]{1,128}$
        salesRep:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 200
            email:
              type: string
              format: email
              maxLength: 254
        fileName:
          type: string
          description: The file name. It must end in .pdf and have no slashes.
          pattern: \.[pP][dD][fF]$
          maxLength: 200
        sandboxScenario:
          $ref: "#/components/schemas/SandboxScenario"
    ContractUploadHeaders:
      type: object
      additionalProperties: false
      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
          const: 0,26214400
      description: Send every header with the PUT, with the exact values.
    CreatedContractUpload:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - uploadUrl
        - uploadHeaders
        - expiresAt
      properties:
        uploadId:
          type: string
          description: The upload id (iup_...).
        uploadUrl:
          type: string
          description: The signed URL. PUT the PDF here within 15 minutes.
          format: uri
        uploadHeaders:
          $ref: "#/components/schemas/ContractUploadHeaders"
        expiresAt:
          type: string
          description: When the upload URL expires.
          format: date-time
    SubmittedContractUpload:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - status
      properties:
        uploadId:
          type: string
        status:
          $ref: "#/components/schemas/UploadStatus"
      description: In production the status is queued. In the Test environment the scenario applies at once, so the status is final.
    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 you see in the Installer Portal.
    ContractUpload:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - status
        - outcome
        - outcomeMessage
        - projectId
        - externalId
        - errors
        - actions
        - createdAt
        - updatedAt
      properties:
        uploadId:
          type: string
        status:
          $ref: "#/components/schemas/UploadStatus"
        outcome:
          oneOf:
            - $ref: "#/components/schemas/UploadOutcome"
            - type: "null"
        outcomeMessage:
          type: string
          description: A plain message for your user. It says what to do next.
        projectId:
          type:
            - string
            - "null"
          description: The PE Project ID, when status is project_created.
        externalId:
          type:
            - string
            - "null"
        errors:
          type: array
          items:
            $ref: "#/components/schemas/UploadCheck"
          description: The failed checks of the review.
        actions:
          type: array
          items:
            $ref: "#/components/schemas/Action"
          description: The open Actions of the new project, in the same shape as GET /projects/{projectId}/actions.
        createdAt:
          type:
            - string
            - "null"
          format: date-time
        updatedAt:
          type:
            - string
            - "null"
          format: date-time
    ApprovalPair:
      type: object
      additionalProperties: false
      required:
        - ic
        - pc
      properties:
        ic:
          $ref: "#/components/schemas/Approval"
        pc:
          $ref: "#/components/schemas/Approval"
    ProjectSummary:
      type: object
      additionalProperties: false
      required:
        - projectId
        - externalId
        - status
        - deleted
        - milestone
        - documentReviewStatus
        - customer
        - site
        - approvals
        - actions
        - updatedAt
      properties:
        projectId:
          type: string
          description: The PE Project ID.
        externalId:
          type:
            - string
            - "null"
        status:
          type:
            - string
            - "null"
          description: The project status, for example Active or Cancelled.
        deleted:
          type: boolean
          description: True when the project is cancelled. It stays readable.
        milestone:
          type:
            - string
            - "null"
        documentReviewStatus:
          type:
            - string
            - "null"
          description: Action Required (Installer), Under Review (PE) or Approved.
        customer:
          type: object
          additionalProperties: false
          required:
            - firstName
            - lastName
          properties:
            firstName:
              type:
                - string
                - "null"
            lastName:
              type:
                - string
                - "null"
        site:
          type: object
          additionalProperties: false
          required:
            - city
            - state
            - stateCode
          properties:
            city:
              type:
                - string
                - "null"
            state:
              type:
                - string
                - "null"
            stateCode:
              type:
                - string
                - "null"
        approvals:
          $ref: "#/components/schemas/ApprovalPair"
        actions:
          type: object
          additionalProperties: false
          required:
            - open
          properties:
            open:
              type: integer
        updatedAt:
          type:
            - string
            - "null"
          format: date-time
    ProjectList:
      type: object
      additionalProperties: false
      required:
        - projects
        - nextCursor
      properties:
        projects:
          type: array
          items:
            $ref: "#/components/schemas/ProjectSummary"
        nextCursor:
          type:
            - string
            - "null"
    ProjectFinancials:
      type: object
      additionalProperties: false
      required:
        - epcAmount
        - eligibleRoofingCost
        - adjustedEpcAmount
        - ineligibleRoofingCost
        - replacementCost
        - leaseFactor
        - discountedAmount
        - baselineLeaseAmount
        - stateIncentive
        - utilityIncentive
        - netAmountDue
        - pePayout
        - icPayment
        - pcPayment
        - dcBonusRecipient
        - lender
        - amountFinanced
        - insuranceOption
        - insuranceRiskAdjustment
        - salesTaxRate
        - salesTaxAmount
      properties:
        epcAmount:
          type:
            - number
            - "null"
        eligibleRoofingCost:
          type:
            - number
            - "null"
        adjustedEpcAmount:
          type:
            - number
            - "null"
        ineligibleRoofingCost:
          type:
            - number
            - "null"
        replacementCost:
          type:
            - number
            - "null"
        leaseFactor:
          type:
            - number
            - "null"
        discountedAmount:
          type:
            - number
            - "null"
        baselineLeaseAmount:
          type:
            - number
            - "null"
        stateIncentive:
          type:
            - number
            - "null"
        utilityIncentive:
          type:
            - number
            - "null"
        netAmountDue:
          type:
            - number
            - "null"
        pePayout:
          type:
            - number
            - "null"
        icPayment:
          type:
            - number
            - "null"
        pcPayment:
          type:
            - number
            - "null"
        dcBonusRecipient:
          type:
            - string
            - "null"
          description: Installer or Customer.
        lender:
          type:
            - string
            - "null"
        amountFinanced:
          type:
            - boolean
            - "null"
        insuranceOption:
          type:
            - string
            - "null"
          description: "\"1\", \"2\" or \"3\"."
        insuranceRiskAdjustment:
          type:
            - number
            - "null"
        salesTaxRate:
          type:
            - number
            - "null"
        salesTaxAmount:
          type:
            - number
            - "null"
      description: The stored pricing chain. See The pricing chain on a project.
    EquipmentRow:
      type: object
      additionalProperties: false
      required:
        - category
        - avlItemId
        - name
        - manufacturer
        - model
        - quantity
      properties:
        category:
          $ref: "#/components/schemas/EquipmentCategory"
        avlItemId:
          type:
            - string
            - "null"
          description: The AVL item, when the equipment is matched to the AVL.
        name:
          type: string
          description: The equipment string on the project.
        manufacturer:
          type:
            - string
            - "null"
        model:
          type:
            - string
            - "null"
        quantity:
          type:
            - integer
            - "null"
    ProjectSystem:
      type: object
      additionalProperties: false
      required:
        - type
        - sizeKw
        - storageKwh
        - equipment
      properties:
        type:
          type:
            - string
            - "null"
          description: Solar Only, PV+Storage or Storage Only.
        sizeKw:
          type:
            - number
            - "null"
        storageKwh:
          type:
            - number
            - "null"
        equipment:
          type: array
          items:
            $ref: "#/components/schemas/EquipmentRow"
    ProjectDetail:
      type: object
      additionalProperties: false
      required:
        - projectId
        - externalId
        - status
        - deleted
        - milestone
        - documentReviewStatus
        - productType
        - contractType
        - source
        - createdAt
        - updatedAt
        - customer
        - site
        - utility
        - existingSolarOnProperty
        - installer
        - dates
        - approvals
        - financials
        - safeHarbor
        - system
        - documents
        - photos
        - actions
        - editability
      properties:
        projectId:
          type: string
          description: The PE Project ID.
        externalId:
          type:
            - string
            - "null"
          description: Your id for the project.
        status:
          type:
            - string
            - "null"
        deleted:
          type: boolean
          description: True when the project is cancelled. It stays readable and cannot change.
        milestone:
          type:
            - string
            - "null"
        documentReviewStatus:
          type:
            - string
            - "null"
        productType:
          type:
            - string
            - "null"
        contractType:
          type:
            - string
            - "null"
        source:
          type: object
          additionalProperties: false
          required:
            - channel
          properties:
            channel:
              type:
                - string
                - "null"
              description: How the project was created, for example INSTALLER_API.
            grantId:
              type: string
              description: The grant id of the key that created it (Installer API projects only).
        createdAt:
          type:
            - string
            - "null"
          format: date-time
        updatedAt:
          type:
            - string
            - "null"
          description: Send it as expectedUpdatedAt on a write.
          format: date-time
        customer:
          type: object
          additionalProperties: false
          required:
            - firstName
            - lastName
            - email
            - phone
            - mailingSameAsSite
          properties:
            firstName:
              type:
                - string
                - "null"
            lastName:
              type:
                - string
                - "null"
            email:
              type:
                - string
                - "null"
            phone:
              type:
                - string
                - "null"
            mailingSameAsSite:
              type:
                - boolean
                - "null"
            mailingAddress:
              type: object
              additionalProperties: false
              required:
                - street
                - city
                - state
                - zipCode
              properties:
                street:
                  type:
                    - string
                    - "null"
                city:
                  type:
                    - string
                    - "null"
                state:
                  type:
                    - string
                    - "null"
                zipCode:
                  type:
                    - string
                    - "null"
        cosigner:
          type: object
          additionalProperties: false
          required:
            - firstName
            - lastName
            - email
            - phone
          properties:
            firstName:
              type:
                - string
                - "null"
            lastName:
              type:
                - string
                - "null"
            email:
              type:
                - string
                - "null"
            phone:
              type:
                - string
                - "null"
        site:
          type: object
          additionalProperties: false
          required:
            - street
            - city
            - state
            - stateCode
            - zipCode
          properties:
            street:
              type:
                - string
                - "null"
            city:
              type:
                - string
                - "null"
            state:
              type:
                - string
                - "null"
            stateCode:
              type:
                - string
                - "null"
            zipCode:
              type:
                - string
                - "null"
        utility:
          type: object
          additionalProperties: false
          required:
            - name
          properties:
            name:
              type:
                - string
                - "null"
            meterId:
              type: string
            nameOnBill:
              type: string
        existingSolarOnProperty:
          type:
            - boolean
            - "null"
        installer:
          type: object
          additionalProperties: false
          required:
            - externalId
            - salesRepName
            - salesRepEmail
            - submittedByEmail
          properties:
            externalId:
              type:
                - string
                - "null"
            salesRepName:
              type:
                - string
                - "null"
            salesRepEmail:
              type:
                - string
                - "null"
            submittedByEmail:
              type:
                - string
                - "null"
        dates:
          type: object
          additionalProperties: false
          required:
            - onboarded
            - contractSigned
            - icApproval
            - icPayment
            - pto
            - pcApproval
            - pcPayment
            - forecastedInstall
            - forecastedPto
          properties:
            onboarded:
              type:
                - string
                - "null"
              format: date
            contractSigned:
              type:
                - string
                - "null"
              format: date
            icApproval:
              type:
                - string
                - "null"
              format: date
            icPayment:
              type:
                - string
                - "null"
              format: date
            pto:
              type:
                - string
                - "null"
              format: date
            pcApproval:
              type:
                - string
                - "null"
              format: date
            pcPayment:
              type:
                - string
                - "null"
              format: date
            forecastedInstall:
              type:
                - string
                - "null"
              format: date
            forecastedPto:
              type:
                - string
                - "null"
              format: date
        approvals:
          $ref: "#/components/schemas/ApprovalPair"
        financials:
          $ref: "#/components/schemas/ProjectFinancials"
        safeHarbor:
          type: object
          additionalProperties: false
          required:
            - opportunityId
          properties:
            opportunityId:
              type:
                - string
                - "null"
        system:
          $ref: "#/components/schemas/ProjectSystem"
        documents:
          type: object
          additionalProperties: false
          required:
            - required
            - uploaded
            - approved
            - actionRequired
          properties:
            required:
              type: integer
            uploaded:
              type: integer
            approved:
              type: integer
            actionRequired:
              type: integer
          description: Counts over the required document slots.
        photos:
          type: object
          additionalProperties: false
          required:
            - sectionsRequired
            - sectionsMissing
            - reviewStatus
          properties:
            sectionsRequired:
              type: integer
            sectionsMissing:
              type: array
              items:
                type: string
            reviewStatus:
              type:
                - string
                - "null"
        actions:
          type: object
          additionalProperties: false
          required:
            - open
            - total
          properties:
            open:
              type: integer
            total:
              type: integer
        editability:
          type: object
          additionalProperties: false
          required:
            - fieldsLocked
            - reason
            - changeOrderRequiredAfterIc
            - externalIdEditable
          properties:
            fieldsLocked:
              type: boolean
              description: True outside the edit window. The window is open at Project Onboarded, and at Inspection Complete until PE approves every document (review status Approved). IC approval closes it.
            reason:
              type:
                - string
                - "null"
              description: Why the fields are locked, in plain words.
            changeOrderRequiredAfterIc:
              type: boolean
              description: True after IC approval.
            externalIdEditable:
              type: boolean
              description: Whether PATCH can change externalId now.
    ProjectPatchRequest:
      type: object
      additionalProperties: false
      properties:
        expectedUpdatedAt:
          type: string
          description: The updatedAt you read. PE refuses the change if the project changed after it.
          format: date-time
        customer:
          type: object
          additionalProperties: false
          properties:
            firstName:
              type: string
              minLength: 1
              maxLength: 100
            lastName:
              type: string
              minLength: 1
              maxLength: 100
            email:
              type: string
              format: email
              maxLength: 254
            phone:
              type: string
              description: Digits, spaces, +, -, ( and ). PE stores a 10-digit US number as (NNN) NNN-NNNN, so a read returns that form.
              minLength: 7
              maxLength: 30
        cosigner:
          type: object
          additionalProperties: false
          properties:
            firstName:
              type: string
              minLength: 1
              maxLength: 100
            lastName:
              type: string
              minLength: 1
              maxLength: 100
            email:
              type: string
              format: email
              maxLength: 254
            phone:
              type: string
              description: Digits, spaces, +, -, ( and ). PE stores a 10-digit US number as (NNN) NNN-NNNN, so a read returns that form.
              minLength: 7
              maxLength: 30
        mailingAddress:
          type: object
          additionalProperties: false
          required:
            - sameAsSite
          properties:
            sameAsSite:
              type: boolean
            street:
              type: string
              minLength: 1
              maxLength: 200
            city:
              type: string
              minLength: 1
              maxLength: 100
            state:
              type: string
              description: A 2-letter US state code (50 states and DC), a military post code (AA, AE, AP) or a territory (PR, VI, GU, AS, MP), any case. A mailing address can be a PO Box.
              pattern: ^[A-Za-z]{2}$
            zipCode:
              type: string
              description: 5 digits or ZIP+4. PE stores the 5 digits.
              pattern: ^\d{5}(-\d{4})?$
        utility:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
              description: A name from GET /utilities.
              minLength: 1
              maxLength: 200
            meterId:
              type: string
              minLength: 1
              maxLength: 64
            nameOnBill:
              type: string
              minLength: 1
              maxLength: 200
        salesRep:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 100
            email:
              type: string
              format: email
              maxLength: 254
        externalId:
          type:
            - string
            - "null"
          description: "Your id: 1 to 128 letters, digits, - and _. Null clears it."
          maxLength: 128
    ChangeOrder:
      type: object
      additionalProperties: false
      required:
        - required
        - actionIds
      properties:
        required:
          type: boolean
          description: True when the change needs a signed change order.
        actionIds:
          type: array
          items:
            type: string
          description: The change order Actions PE created.
    ProjectUpdateResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - dryRun
        - changed
        - changedFields
        - resignRequired
        - changeOrder
        - project
      properties:
        projectId:
          type: string
        dryRun:
          type: boolean
        changed:
          type: boolean
        changedFields:
          type: array
          items:
            type: string
          description: The API fields that changed (or would change).
        resignRequired:
          type: boolean
          description: True when the customer must sign the agreement again.
        changeOrder:
          $ref: "#/components/schemas/ChangeOrder"
        project:
          $ref: "#/components/schemas/ProjectDetail"
    FinancialsRequest:
      type: object
      additionalProperties: false
      required:
        - basis
      properties:
        expectedUpdatedAt:
          type: string
          format: date-time
        basis:
          type: string
          enum:
            - epc
            - netAmountDue
        epcAmount:
          type: number
          description: "Basis epc only. The total EPC in USD: 1,000 to 500,000 (v2.2; outside it EPC_OUT_OF_RANGE)."
          minimum: 1000
          maximum: 500000
        targetNetAmountDue:
          type: number
          description: Basis netAmountDue only. 1,000 to 500,000 USD (v2.2; outside it EPC_OUT_OF_RANGE).
          minimum: 1000
          maximum: 500000
        eligibleRoofingCost:
          type: number
          minimum: 0
          maximum: 10000000
        ineligibleRoofingCost:
          type: number
          minimum: 0
          maximum: 10000000
        insuranceOption:
          type: string
          enum:
            - "1"
            - "2"
            - "3"
          description: Stored and returned as "1", "2" or "3". The number 1, 2 or 3 (the pricing form) is accepted too.
        dcBonusRecipient:
          type: string
          enum:
            - Installer
            - Customer
          description: Stored and returned as Installer or Customer. Any case is accepted, including the pricing form installer or customer.
        lender:
          type:
            - string
            - "null"
          minLength: 1
          maxLength: 100
          description: A lender on PE's approved lender list for the project's state (the Installer Portal's Lender list), in any case; PE stores the list's spelling. Another name returns LENDER_NOT_APPROVED with the approved names in details. Null clears the lender.
        amountFinancedByLender:
          type: boolean
    FinancialsResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - basis
        - dryRun
        - changed
        - changedFields
        - changeOrder
        - financials
      properties:
        projectId:
          type: string
        basis:
          type: string
          enum:
            - epc
            - netAmountDue
        targetNetAmountDue:
          type: number
          description: Only on the netAmountDue basis.
        dryRun:
          type: boolean
        changed:
          type: boolean
        changedFields:
          type: array
          items:
            type: string
        changeOrder:
          $ref: "#/components/schemas/ChangeOrder"
        financials:
          $ref: "#/components/schemas/ProjectFinancials"
    EquipmentRequest:
      type: object
      additionalProperties: false
      required:
        - items
      properties:
        expectedUpdatedAt:
          type: string
          format: date-time
        items:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - category
            properties:
              category:
                $ref: "#/components/schemas/EquipmentCategory"
              avlItemId:
                type: string
                description: An AVL item id. Send avlItemId or name.
                pattern: ^[A-Za-z0-9_-]+$
                maxLength: 128
              name:
                type: string
                description: The exact AVL string, or a string on your Equipment Map. Send avlItemId or name.
                minLength: 1
                maxLength: 200
              quantity:
                type: integer
                description: "module and acModule: the module count. inverter: the inverter count. battery: the TOTAL battery units, lead and expansion units together. racking and batteryExpansion have no quantity: leave it out (sending one returns VALIDATION_FAILED)."
                minimum: 1
                maximum: 10000
          description: One item per category.
          minItems: 1
          maxItems: 6
        systemSizeKw:
          type: number
          description: "The system size in kW DC, 0.5 to 250. Never converted: a value in watts returns SYSTEM_SIZE_LOOKS_LIKE_WATTS, another value outside the range SYSTEM_SIZE_OUT_OF_RANGE. With a known module count and wattage it must be within 25% of count x watts / 1000 (SYSTEM_SIZE_MISMATCH). Leave it out to let PE compute it."
          minimum: 0.5
          maximum: 250
    EquipmentResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - dryRun
        - changed
        - changedFields
        - items
        - changeOrder
        - system
      properties:
        projectId:
          type: string
        dryRun:
          type: boolean
        changed:
          type: boolean
        changedFields:
          type: array
          items:
            type: string
        items:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - category
              - avlItemId
              - name
              - matchedBy
            properties:
              category:
                $ref: "#/components/schemas/EquipmentCategory"
              avlItemId:
                type:
                  - string
                  - "null"
              name:
                type: string
              matchedBy:
                type: string
                description: "How PE matched the item: avl_item_id, equipment_map, exact, normalized or custom_avl."
        changeOrder:
          $ref: "#/components/schemas/ChangeOrder"
        system:
          $ref: "#/components/schemas/ProjectSystem"
    SafeHarborRequest:
      type: object
      additionalProperties: false
      required:
        - opportunityId
      properties:
        expectedUpdatedAt:
          type: string
          format: date-time
        opportunityId:
          type:
            - string
            - "null"
          description: An opportunityId from GET /safe-harbor/opportunities. Null unlinks the opportunity.
          pattern: ^[A-Za-z0-9._-]+$
          maxLength: 64
    SafeHarborResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - dryRun
        - changed
        - safeHarbor
        - previousOpportunityId
        - project
      properties:
        projectId:
          type: string
        dryRun:
          type: boolean
          description: True when ?dryRun=true (nothing was written).
        changed:
          type: boolean
        safeHarbor:
          type: object
          additionalProperties: false
          required:
            - opportunityId
          properties:
            opportunityId:
              type:
                - string
                - "null"
        previousOpportunityId:
          type:
            - string
            - "null"
        project:
          $ref: "#/components/schemas/ProjectDetail"
    ActivityEntry:
      type: object
      additionalProperties: false
      required:
        - date
        - activityBy
        - type
        - category
        - notes
        - document
      properties:
        date:
          type:
            - string
            - "null"
          format: date-time
        activityBy:
          type:
            - string
            - "null"
        type:
          type:
            - string
            - "null"
        category:
          type:
            - string
            - "null"
        notes:
          type:
            - string
            - "null"
        document:
          type:
            - object
            - "null"
          additionalProperties: false
          required:
            - type
            - label
          properties:
            type:
              type:
                - string
                - "null"
            label:
              type: string
    ActivityPage:
      type: object
      additionalProperties: false
      required:
        - activity
        - nextCursor
      properties:
        activity:
          type: array
          items:
            $ref: "#/components/schemas/ActivityEntry"
        nextCursor:
          type:
            - string
            - "null"
    DocumentVersion:
      type: object
      additionalProperties: false
      required:
        - version
        - fileName
        - contentType
        - uploadedAt
        - uploadedBy
        - source
        - archived
        - current
      properties:
        version:
          type: integer
        fileName:
          type:
            - string
            - "null"
        contentType:
          type:
            - string
            - "null"
        uploadedAt:
          type:
            - string
            - "null"
          format: date-time
        uploadedBy:
          type:
            - string
            - "null"
        source:
          type:
            - string
            - "null"
        archived:
          type: boolean
        current:
          type: boolean
          description: The current file of the slot.
    SibylFeedback:
      type: object
      additionalProperties: false
      required:
        - state
        - reviewedAt
      properties:
        state:
          type:
            - string
            - "null"
          enum:
            - processing
            - clean
            - warn
            - gray
            - null
          description: processing, clean, warn, gray, or null. See Automated review.
        reviewedAt:
          type:
            - string
            - "null"
          format: date-time
    ActionSummary:
      type: object
      additionalProperties: false
      required:
        - actionId
        - severity
        - title
        - description
        - nextStep
        - category
      properties:
        actionId:
          type: string
        severity:
          type: string
          enum:
            - fail
            - warn
        title:
          type: string
        description:
          type: string
        nextStep:
          type:
            - string
            - "null"
        category:
          type:
            - string
            - "null"
    ReviewActivity:
      type: object
      additionalProperties: false
      required:
        - at
        - type
        - notes
        - by
      properties:
        at:
          type:
            - string
            - "null"
          format: date-time
        type:
          type:
            - string
            - "null"
        notes:
          type:
            - string
            - "null"
        by:
          type:
            - string
            - "null"
    DocumentSlot:
      type: object
      additionalProperties: false
      required:
        - documentType
        - label
        - required
        - blocking
        - stage
        - requestedAt
        - reviewStatus
        - submittedAt
        - reviewerComments
        - uploadOpen
        - uploadClosedReason
        - acceptedContentTypes
        - maxFileBytes
        - currentVersion
        - versions
        - sibyl
        - openActions
        - reviewActivity
      properties:
        documentType:
          type: string
          description: Use it in the document paths.
        label:
          type: string
        required:
          type: boolean
        blocking:
          type: boolean
          description: A missing or open document blocks review.
        stage:
          type: string
          enum:
            - ic
            - pc
        requestedAt:
          type: string
        reviewStatus:
          type:
            - string
            - "null"
        submittedAt:
          type:
            - string
            - "null"
        reviewerComments:
          type:
            - string
            - "null"
        uploadOpen:
          type: boolean
        uploadClosedReason:
          type:
            - string
            - "null"
        acceptedContentTypes:
          type: array
          items:
            type: string
        maxFileBytes:
          type: integer
        currentVersion:
          type:
            - integer
            - "null"
        versions:
          type: array
          items:
            $ref: "#/components/schemas/DocumentVersion"
        sibyl:
          $ref: "#/components/schemas/SibylFeedback"
        openActions:
          type: array
          items:
            $ref: "#/components/schemas/ActionSummary"
        reviewActivity:
          type: array
          items:
            $ref: "#/components/schemas/ReviewActivity"
          description: The latest review entries for the slot, newest first.
        monitoringState:
          type:
            - string
            - "null"
          description: "Access to Monitoring only: the state of the site IDs."
    DocumentList:
      type: object
      additionalProperties: false
      required:
        - projectId
        - documents
      properties:
        projectId:
          type: string
        documents:
          type: array
          items:
            $ref: "#/components/schemas/DocumentSlot"
    DocumentDownload:
      type: object
      additionalProperties: false
      required:
        - projectId
        - documentType
        - version
        - fileName
        - contentType
        - archived
        - downloadUrl
        - expiresAt
      properties:
        projectId:
          type: string
        documentType:
          type: string
        version:
          type: integer
        fileName:
          type:
            - string
            - "null"
        contentType:
          type:
            - string
            - "null"
        archived:
          type: boolean
        downloadUrl:
          type: string
          description: A signed GET URL, valid for 15 minutes.
          format: uri
        expiresAt:
          type: string
          format: date-time
    CreateDocumentUploadRequest:
      type: object
      additionalProperties: false
      required:
        - fileName
        - contentType
      properties:
        fileName:
          type: string
          description: "A plain file name, no slashes, that ends in an extension of contentType (v2.2): .pdf, .jpg or .jpeg, .png, .heic or .heif. Another extension returns VALIDATION_FAILED naming fileName."
          minLength: 1
          maxLength: 200
        contentType:
          type: string
          enum:
            - application/pdf
            - image/jpeg
            - image/png
            - image/heic
            - image/heif
          description: The file type.
    CreatedDocumentUpload:
      type: object
      additionalProperties: false
      required:
        - projectId
        - documentType
        - fileUploadId
        - uploadUrl
        - uploadMethod
        - uploadHeaders
        - maxBytes
        - expiresAt
      properties:
        projectId:
          type: string
        documentType:
          type: string
        fileUploadId:
          type: string
          description: The upload id (ifu_...).
        uploadUrl:
          type: string
          description: The signed PUT URL, valid for 15 minutes.
          format: uri
        uploadMethod:
          type: string
          const: PUT
        uploadHeaders:
          type: object
          additionalProperties: false
          required:
            - Content-Type
            - x-goog-if-generation-match
            - x-goog-content-length-range
          properties:
            Content-Type:
              type: string
              description: The contentType you declared.
            x-goog-if-generation-match:
              type: string
              const: "0"
            x-goog-content-length-range:
              type: string
              const: 0,52428800
          description: Send every header with the PUT, with the exact values.
        maxBytes:
          type: integer
        expiresAt:
          type: string
          format: date-time
    ConfirmUploadRequest:
      type: object
      additionalProperties: false
      properties:
        notes:
          type: string
          description: A note for the reviewer.
          minLength: 1
          maxLength: 2000
        resolveActionIds:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 400
          description: The open Actions this upload answers. An id that cannot be an Action id (for example one with a /) is returned in skippedActionIds.
          maxItems: 20
    ConfirmedDocumentUpload:
      type: object
      additionalProperties: false
      required:
        - projectId
        - documentType
        - fileUploadId
        - version
        - reviewStatus
        - reviewQueued
        - resolvedActionIds
        - skippedActionIds
      properties:
        projectId:
          type: string
        documentType:
          type: string
        fileUploadId:
          type: string
        version:
          type:
            - integer
            - "null"
        reviewStatus:
          type:
            - string
            - "null"
        reviewQueued:
          type: boolean
          description: True when an automated review started.
        resolvedActionIds:
          type: array
          items:
            type: string
        skippedActionIds:
          type: array
          items:
            type: string
    ArchiveRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
          description: Why the version is archived.
          minLength: 1
          maxLength: 500
    ArchiveResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - documentType
        - version
        - archived
        - changed
        - currentChanged
      properties:
        projectId:
          type: string
        documentType:
          type: string
        version:
          type: integer
        archived:
          type: boolean
        changed:
          type: boolean
        currentChanged:
          type: boolean
          description: The write changed which file is current.
    PhotoFile:
      type: object
      additionalProperties: false
      required:
        - version
        - fileName
        - contentType
        - uploadedAt
        - uploadedBy
        - archived
        - batchId
      properties:
        version:
          type: integer
        fileName:
          type:
            - string
            - "null"
        contentType:
          type:
            - string
            - "null"
        uploadedAt:
          type:
            - string
            - "null"
          format: date-time
        uploadedBy:
          type:
            - string
            - "null"
        archived:
          type: boolean
        batchId:
          type:
            - string
            - "null"
    PhotoCategory:
      type: object
      additionalProperties: false
      required:
        - category
        - label
        - description
        - required
        - covered
        - files
      properties:
        category:
          type: string
        label:
          type: string
        description:
          type:
            - string
            - "null"
        required:
          type: boolean
        covered:
          type: boolean
          description: The category has at least one file.
        files:
          type: array
          items:
            $ref: "#/components/schemas/PhotoFile"
    PhotoList:
      type: object
      additionalProperties: false
      required:
        - projectId
        - systemType
        - reviewStatus
        - submittedAt
        - reviewerComments
        - uploadOpen
        - uploadClosedReason
        - acceptedContentTypes
        - maxFileBytes
        - maxFilesPerUpload
        - sectionsMissing
        - coverageApplies
        - categories
        - openActions
      properties:
        projectId:
          type: string
        systemType:
          type:
            - string
            - "null"
        reviewStatus:
          type:
            - string
            - "null"
        submittedAt:
          type:
            - string
            - "null"
        reviewerComments:
          type:
            - string
            - "null"
        uploadOpen:
          type: boolean
        uploadClosedReason:
          type:
            - string
            - "null"
        acceptedContentTypes:
          type: array
          items:
            type: string
        maxFileBytes:
          type: integer
        maxFilesPerUpload:
          type: integer
        sectionsMissing:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - category
              - label
            properties:
              category:
                type: string
              label:
                type: string
        coverageApplies:
          type: boolean
        categories:
          type: array
          items:
            $ref: "#/components/schemas/PhotoCategory"
        openActions:
          type: array
          items:
            $ref: "#/components/schemas/ActionSummary"
    CreatePhotoUploadRequest:
      type: object
      additionalProperties: false
      required:
        - files
      properties:
        files:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - fileName
              - contentType
            properties:
              fileName:
                type: string
                minLength: 1
                maxLength: 200
              contentType:
                type: string
                enum:
                  - application/pdf
                  - image/jpeg
                  - image/png
                  - image/heic
                  - image/heif
                  - image/webp
                  - image/gif
          minItems: 1
          maxItems: 25
    CreatedPhotoUpload:
      type: object
      additionalProperties: false
      required:
        - projectId
        - category
        - batchId
        - files
        - maxBytes
        - expiresAt
      properties:
        projectId:
          type: string
        category:
          type: string
        batchId:
          type: string
          description: The batch id (ifu_...).
        files:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - index
              - fileName
              - uploadUrl
              - uploadMethod
              - uploadHeaders
            properties:
              index:
                type: integer
              fileName:
                type: string
              uploadUrl:
                type: string
                format: uri
              uploadMethod:
                type: string
                const: PUT
              uploadHeaders:
                type: object
                additionalProperties: false
                required:
                  - Content-Type
                  - x-goog-if-generation-match
                  - x-goog-content-length-range
                properties:
                  Content-Type:
                    type: string
                    description: The contentType you declared.
                  x-goog-if-generation-match:
                    type: string
                    const: "0"
                  x-goog-content-length-range:
                    type: string
                    const: 0,104857600
                description: Send every header with the PUT, with the exact values.
        maxBytes:
          type: integer
        expiresAt:
          type: string
          format: date-time
    ConfirmedPhotoUpload:
      type: object
      additionalProperties: false
      required:
        - projectId
        - category
        - batchId
        - uploaded
        - versions
        - deduped
        - sectionsMissing
        - reviewStatus
        - reviewQueued
        - resolvedActionIds
        - skippedActionIds
      properties:
        projectId:
          type: string
        category:
          type: string
        batchId:
          type: string
        uploaded:
          type: integer
          description: New files added.
        versions:
          type: array
          items:
            type: integer
          description: The new versions, in file order.
        deduped:
          type: integer
          description: Files that were already on the slot.
        sectionsMissing:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - category
              - label
            properties:
              category:
                type: string
              label:
                type: string
        reviewStatus:
          type:
            - string
            - "null"
        reviewQueued:
          type: boolean
        resolvedActionIds:
          type: array
          items:
            type: string
        skippedActionIds:
          type: array
          items:
            type: string
    MonitoringSite:
      type: object
      additionalProperties: false
      required:
        - provider
        - manufacturer
        - siteId
        - siteName
        - roles
        - enteredAt
        - verification
      properties:
        provider:
          type: string
        manufacturer:
          type:
            - string
            - "null"
        siteId:
          type: string
        siteName:
          type:
            - string
            - "null"
        roles:
          type: array
          items:
            type: string
        enteredAt:
          type:
            - string
            - "null"
        verification:
          type:
            - object
            - "null"
          additionalProperties: false
          required:
            - status
            - checkedAt
            - checks
          properties:
            status:
              type: string
            checkedAt:
              type:
                - string
                - "null"
            checks:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                  - check
                  - label
                  - status
                  - message
                properties:
                  check:
                    type: string
                  label:
                    type: string
                  status:
                    type: string
                  message:
                    type:
                      - string
                      - "null"
    MonitoringAccess:
      type: object
      additionalProperties: false
      required:
        - projectId
        - required
        - anyProvider
        - notRequiredProviders
        - sites
        - state
        - reviewStatus
        - lastRun
        - sitesEditable
        - icApproved
        - exceptionRequested
        - baseSitesHash
        - updatedAt
      properties:
        projectId:
          type: string
        required:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - role
              - provider
              - manufacturer
            properties:
              role:
                type: string
              provider:
                type: string
              manufacturer:
                type: string
          description: The providers the project's equipment needs.
        anyProvider:
          type: boolean
        notRequiredProviders:
          type: array
          items:
            type: string
        sites:
          type: array
          items:
            $ref: "#/components/schemas/MonitoringSite"
        state:
          type:
            - string
            - "null"
          description: The state of the site IDs, for example verifying, partial or verified.
        reviewStatus:
          type:
            - string
            - "null"
        lastRun:
          type:
            - object
            - "null"
          additionalProperties: false
          required:
            - status
            - requestedAt
            - finishedAt
            - outcome
          properties:
            status:
              type: string
            requestedAt:
              type:
                - string
                - "null"
            finishedAt:
              type:
                - string
                - "null"
            outcome:
              type:
                - string
                - "null"
        sitesEditable:
          type: boolean
        icApproved:
          type: boolean
        exceptionRequested:
          type: boolean
        baseSitesHash:
          type:
            - string
            - "null"
          description: Send it back as baseSitesHash on the next save.
        updatedAt:
          type:
            - string
            - "null"
    MonitoringAccessRequest:
      type: object
      additionalProperties: false
      required:
        - sites
      properties:
        sites:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - provider
              - siteId
            properties:
              provider:
                $ref: "#/components/schemas/MonitoringProvider"
              manufacturer:
                type: string
                minLength: 1
                maxLength: 100
              siteId:
                type: string
                minLength: 1
                maxLength: 200
          description: All the sites of the project.
          maxItems: 10
        verify:
          type: string
          enum:
            - now
            - offline
          description: Default now.
        baseSitesHash:
          type: string
          minLength: 1
          maxLength: 128
        resolveActionIds:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 200
          maxItems: 20
    MonitoringAccessView:
      type: object
      additionalProperties: false
      required:
        - required
        - anyProvider
        - notRequiredProviders
        - sites
        - state
        - reviewStatus
        - lastRun
        - sitesEditable
        - icApproved
        - exceptionRequested
        - baseSitesHash
        - updatedAt
      properties:
        required:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - role
              - provider
              - manufacturer
            properties:
              role:
                type: string
              provider:
                type: string
              manufacturer:
                type: string
          description: The providers the project's equipment needs.
        anyProvider:
          type: boolean
        notRequiredProviders:
          type: array
          items:
            type: string
        sites:
          type: array
          items:
            $ref: "#/components/schemas/MonitoringSite"
        state:
          type:
            - string
            - "null"
          description: The state of the site IDs, for example verifying, partial or verified.
        reviewStatus:
          type:
            - string
            - "null"
        lastRun:
          type:
            - object
            - "null"
          additionalProperties: false
          required:
            - status
            - requestedAt
            - finishedAt
            - outcome
          properties:
            status:
              type: string
            requestedAt:
              type:
                - string
                - "null"
            finishedAt:
              type:
                - string
                - "null"
            outcome:
              type:
                - string
                - "null"
        sitesEditable:
          type: boolean
        icApproved:
          type: boolean
        exceptionRequested:
          type: boolean
        baseSitesHash:
          type:
            - string
            - "null"
          description: Send it back as baseSitesHash on the next save.
        updatedAt:
          type:
            - string
            - "null"
    MonitoringAccessResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - state
        - acceptedActionIds
        - skippedActionIds
        - monitoringAccess
      properties:
        projectId:
          type: string
        state:
          type:
            - string
            - "null"
        acceptedActionIds:
          type: array
          items:
            type: string
          description: Actions PE resolves when the check passes.
        skippedActionIds:
          type: array
          items:
            type: string
        monitoringAccess:
          $ref: "#/components/schemas/MonitoringAccessView"
    Action:
      type: object
      additionalProperties: false
      required:
        - actionId
        - status
        - severity
        - title
        - description
        - code
        - resolution
        - nextStep
        - category
        - documentType
        - documentSlot
        - pageRefs
        - createdAt
        - updatedAt
        - resolvedAt
        - notes
        - history
      properties:
        actionId:
          type: string
        status:
          $ref: "#/components/schemas/ActionStatus"
        severity:
          type: string
          enum:
            - fail
            - warn
        title:
          type: string
        description:
          type: string
        code:
          type:
            - string
            - "null"
          description: The issue code.
        resolution:
          type:
            - string
            - "null"
        nextStep:
          type:
            - string
            - "null"
          description: What to do.
        category:
          type:
            - string
            - "null"
          description: Who created the Action, for example sibyl or manual.
        documentType:
          type:
            - string
            - "null"
        documentSlot:
          type:
            - string
            - "null"
        pageRefs:
          type: array
          items:
            type: integer
        createdAt:
          type:
            - string
            - "null"
          format: date-time
        updatedAt:
          type:
            - string
            - "null"
          format: date-time
        resolvedAt:
          type:
            - string
            - "null"
          format: date-time
        notes:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - text
              - by
              - at
            properties:
              text:
                type: string
              by:
                type:
                  - string
                  - "null"
              at:
                type:
                  - string
                  - "null"
                format: date-time
        history:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - kind
              - at
              - by
            properties:
              kind:
                type: string
              at:
                type:
                  - string
                  - "null"
                format: date-time
              by:
                type:
                  - string
                  - "null"
              statusFrom:
                type:
                  - string
                  - "null"
              statusTo:
                type: string
              note:
                type: string
    ActionList:
      type: object
      additionalProperties: false
      required:
        - projectId
        - actions
        - counts
      properties:
        projectId:
          type: string
        actions:
          type: array
          items:
            $ref: "#/components/schemas/Action"
        counts:
          type: object
          additionalProperties: false
          required:
            - total
            - open
          properties:
            total:
              type: integer
            open:
              type: integer
    ActionResponse:
      type: object
      additionalProperties: false
      required:
        - projectId
        - action
      properties:
        projectId:
          type: string
        action:
          $ref: "#/components/schemas/Action"
    ActionResolveResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - statusChanged
        - action
      properties:
        projectId:
          type: string
        statusChanged:
          type: boolean
          description: False when the Action was already resolved.
        action:
          $ref: "#/components/schemas/Action"
    NoteRequest:
      type: object
      additionalProperties: false
      required:
        - note
      properties:
        note:
          type: string
          minLength: 1
          maxLength: 2000
    SetWebhookRequest:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          description: An https URL on port 443 with a public host.
          minLength: 1
          maxLength: 2048
          format: uri
    Webhook:
      type: object
      additionalProperties: false
      required:
        - url
        - events
        - secretVersion
      properties:
        url:
          type:
            - string
            - "null"
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
        secretVersion:
          type:
            - integer
            - "null"
    WebhookWithSecret:
      type: object
      additionalProperties: false
      required:
        - url
        - events
        - secretVersion
        - signingSecret
      properties:
        url:
          type: string
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
        secretVersion:
          type: integer
        signingSecret:
          type:
            - string
            - "null"
          description: whsec_... Shown for a new subscription and after a rotation. Null when you only changed the URL.
    WebhookDeleted:
      type: object
      additionalProperties: false
      required:
        - url
        - deleted
      properties:
        url:
          type: "null"
        deleted:
          type: boolean
          const: true
    WebhookTestResult:
      type: object
      additionalProperties: false
      required:
        - eventId
        - type
        - delivered
        - statusCode
        - durationMs
      properties:
        eventId:
          type: string
        type:
          type: string
          const: webhook.test
        delivered:
          type: boolean
        statusCode:
          type:
            - integer
            - "null"
        durationMs:
          type: integer
        error:
          type: string
    ApprovalEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - createdAt
        - environment
        - data
      properties:
        id:
          type: string
          description: The event id (evt_...). Same as PE-Event-Id.
        type:
          type: string
          enum:
            - project.ic_approved
            - project.pc_approved
        createdAt:
          type: string
          format: date-time
        environment:
          $ref: "#/components/schemas/Environment"
        data:
          type: object
          additionalProperties: false
          required:
            - projectId
            - externalId
            - approval
          properties:
            projectId:
              type: string
            externalId:
              type:
                - string
                - "null"
            approval:
              type: object
              additionalProperties: false
              required:
                - stage
                - approvedAt
              properties:
                stage:
                  type: string
                  enum:
                    - ic
                    - pc
                approvedAt:
                  type:
                    - string
                    - "null"
                  format: date
    ActionCreatedEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - createdAt
        - environment
        - data
      properties:
        id:
          type: string
          description: The event id (evt_...). Same as PE-Event-Id.
        type:
          type: string
          const: project.action_created
        createdAt:
          type: string
          format: date-time
        environment:
          $ref: "#/components/schemas/Environment"
        data:
          type: object
          additionalProperties: false
          required:
            - projectId
            - externalId
            - action
          properties:
            projectId:
              type: string
            externalId:
              type:
                - string
                - "null"
            action:
              $ref: "#/components/schemas/Action"
    TestEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - createdAt
        - environment
        - data
      properties:
        id:
          type: string
        type:
          type: string
          const: webhook.test
        createdAt:
          type: string
          format: date-time
        environment:
          $ref: "#/components/schemas/Environment"
        data:
          type: object
          additionalProperties: false
          properties: {}
    SimulateRequest:
      type: object
      additionalProperties: false
      required:
        - event
      properties:
        event:
          $ref: "#/components/schemas/SimulateEvent"
        documentType:
          type: string
          description: document_approved, document_rejected; optional on action_raised.
          minLength: 1
          maxLength: 100
        reason:
          type: string
          description: "document_rejected: the reviewer comment. contract_declined and contract_voided (optional): the reason."
          minLength: 1
          maxLength: 1000
        title:
          type: string
          description: "action_raised: the Action title."
          minLength: 1
          maxLength: 200
    SimulateResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - event
        - changed
        - status
        - milestone
        - documentReviewStatus
        - approvals
        - openActions
        - actionId
        - contract
      properties:
        projectId:
          type: string
        event:
          $ref: "#/components/schemas/SimulateEvent"
        changed:
          type: boolean
          description: False when the event changed nothing (for example, already approved).
        status:
          type:
            - string
            - "null"
        milestone:
          type:
            - string
            - "null"
        documentReviewStatus:
          type:
            - string
            - "null"
        approvals:
          $ref: "#/components/schemas/ApprovalPair"
        openActions:
          type:
            - integer
            - "null"
        actionId:
          type:
            - string
            - "null"
          description: The Action the event created.
        contract:
          type:
            - object
            - "null"
          additionalProperties: false
          required:
            - packetId
            - status
            - signers
          description: The Test contract after a contract_* event; null for the other events.
          properties:
            packetId:
              type: string
            status:
              $ref: "#/components/schemas/ContractStatus"
            signers:
              type: array
              items:
                $ref: "#/components/schemas/ContractEsignSigner"
    ScenarioList:
      type: object
      additionalProperties: false
      required:
        - scenarios
      properties:
        scenarios:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - scenario
              - default
              - description
              - status
              - outcome
              - outcomeMessage
              - createsProject
              - initialActions
            properties:
              scenario:
                $ref: "#/components/schemas/SandboxScenario"
              default:
                type: boolean
              description:
                type: string
              status:
                type: string
              outcome:
                $ref: "#/components/schemas/UploadOutcome"
              outcomeMessage:
                type: string
              createsProject:
                type: boolean
              initialActions:
                type: integer
    PingResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Ping"
        meta:
          $ref: "#/components/schemas/Meta"
    MeResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Me"
        meta:
          $ref: "#/components/schemas/Meta"
    AvlPageResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/AvlPage"
        meta:
          $ref: "#/components/schemas/Meta"
    AvlItemResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/AvlItem"
        meta:
          $ref: "#/components/schemas/Meta"
    SafeHarborOpportunityListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SafeHarborOpportunityList"
        meta:
          $ref: "#/components/schemas/Meta"
    SafeHarborOpportunityDetailResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SafeHarborOpportunityDetail"
        meta:
          $ref: "#/components/schemas/Meta"
    UtilityListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/UtilityList"
        meta:
          $ref: "#/components/schemas/Meta"
    StateListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/StateList"
        meta:
          $ref: "#/components/schemas/Meta"
    EquipmentMapPageResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/EquipmentMapPage"
        meta:
          $ref: "#/components/schemas/Meta"
    ReferenceResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Reference"
        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"
    EnergyCommunityResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/EnergyCommunity"
        meta:
          $ref: "#/components/schemas/Meta"
    SalesTaxCheckResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SalesTaxCheck"
        meta:
          $ref: "#/components/schemas/Meta"
    LeasePriceQuoteResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/LeasePriceQuote"
        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"
    CreatedContractUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/CreatedContractUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    SubmittedContractUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SubmittedContractUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    ProjectListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ProjectList"
        meta:
          $ref: "#/components/schemas/Meta"
    ProjectDetailResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ProjectDetail"
        meta:
          $ref: "#/components/schemas/Meta"
    ProjectUpdateResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ProjectUpdateResult"
        meta:
          $ref: "#/components/schemas/Meta"
    FinancialsResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/FinancialsResult"
        meta:
          $ref: "#/components/schemas/Meta"
    EquipmentResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/EquipmentResult"
        meta:
          $ref: "#/components/schemas/Meta"
    SafeHarborResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SafeHarborResult"
        meta:
          $ref: "#/components/schemas/Meta"
    ActivityPageResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ActivityPage"
        meta:
          $ref: "#/components/schemas/Meta"
    DocumentListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/DocumentList"
        meta:
          $ref: "#/components/schemas/Meta"
    DocumentDownloadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/DocumentDownload"
        meta:
          $ref: "#/components/schemas/Meta"
    CreatedDocumentUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/CreatedDocumentUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    ConfirmedDocumentUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ConfirmedDocumentUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    ArchiveResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ArchiveResult"
        meta:
          $ref: "#/components/schemas/Meta"
    PhotoListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/PhotoList"
        meta:
          $ref: "#/components/schemas/Meta"
    CreatedPhotoUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/CreatedPhotoUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    ConfirmedPhotoUploadResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ConfirmedPhotoUpload"
        meta:
          $ref: "#/components/schemas/Meta"
    MonitoringAccessResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/MonitoringAccess"
        meta:
          $ref: "#/components/schemas/Meta"
    MonitoringAccessResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/MonitoringAccessResult"
        meta:
          $ref: "#/components/schemas/Meta"
    ActionListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ActionList"
        meta:
          $ref: "#/components/schemas/Meta"
    ActionResponseResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ActionResponse"
        meta:
          $ref: "#/components/schemas/Meta"
    ActionResolveResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ActionResolveResult"
        meta:
          $ref: "#/components/schemas/Meta"
    WebhookResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/Webhook"
        meta:
          $ref: "#/components/schemas/Meta"
    WebhookWithSecretResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/WebhookWithSecret"
        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"
    SimulateResultResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/SimulateResult"
        meta:
          $ref: "#/components/schemas/Meta"
    ScenarioListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ScenarioList"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractStatus:
      type: string
      enum:
        - sent
        - partially_signed
        - completed
        - declined
        - voided
        - expired
        - cancelled
      description: The status of a contract sent for e-signature.
    SignerStatus:
      type: string
      enum:
        - pending
        - sent
        - viewed
        - signed
        - declined
      description: "pending: not their turn yet. sent: their turn, the link is out. viewed, signed, declined."
    ContractSigner:
      type: object
      additionalProperties: false
      required:
        - role
        - name
        - email
        - status
      properties:
        role:
          type: string
          description: customer, cosigner, installer or pe.
        name:
          type:
            - string
            - "null"
        email:
          type:
            - string
            - "null"
          description: null for the pe signer.
        status:
          $ref: "#/components/schemas/SignerStatus"
    ContractEsignSigner:
      type: object
      additionalProperties: false
      required:
        - role
        - name
        - email
        - status
        - signedAt
        - viewed
      properties:
        role:
          type: string
          description: customer, cosigner, installer or pe.
        name:
          type:
            - string
            - "null"
        email:
          type:
            - string
            - "null"
          description: null for the pe signer.
        status:
          $ref: "#/components/schemas/SignerStatus"
        signedAt:
          type:
            - string
            - "null"
          format: date-time
        viewed:
          type: boolean
    ContractSendResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - packetId
        - draftId
        - status
        - installerSignMethod
        - installerSigningUrl
        - signers
        - testMode
        - warnings
      properties:
        projectId:
          type: string
          description: The PE Project ID of the project (SBX-... for Test keys).
        packetId:
          type: string
          description: The contract sent for e-signature.
        draftId:
          type:
            - string
            - "null"
          description: The draft that was sent; null for a send of an existing project.
        status:
          $ref: "#/components/schemas/ContractStatus"
        installerSignMethod:
          type:
            - string
            - "null"
          description: "auto_applied: your default signer's signature was applied at send. email: the installer signer gets a link."
        installerSigningUrl:
          type:
            - string
            - "null"
          description: "Always null today: the installer line is signed at send."
        signers:
          type: array
          items:
            $ref: "#/components/schemas/ContractSigner"
        testMode:
          type: boolean
          description: True for a Test key (nothing was emailed).
        warnings:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Notes about the created project, for example a Hawaii RETITC change. A repeated draft send whose contract is no longer out for signature adds PACKET_NOT_OPEN.
    ContractSendResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractSendResult"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractDocument:
      type: object
      additionalProperties: false
      required:
        - name
        - url
        - expiresAt
      properties:
        name:
          type: string
        url:
          type: string
          description: A download link that works for 15 minutes.
        expiresAt:
          type: string
          format: date-time
    ContractEsign:
      type: object
      additionalProperties: false
      required:
        - projectId
        - packetId
        - status
        - templateName
        - installerSignMethod
        - sentAt
        - completedAt
        - expiresAt
        - voidedReason
        - declineReason
        - signers
        - testMode
        - documentsRendered
        - documentsNotRenderedReason
        - documents
      properties:
        projectId:
          type: string
        packetId:
          type: string
        status:
          $ref: "#/components/schemas/ContractStatus"
        templateName:
          type:
            - string
            - "null"
        installerSignMethod:
          type:
            - string
            - "null"
        sentAt:
          type:
            - string
            - "null"
          format: date-time
        completedAt:
          type:
            - string
            - "null"
          format: date-time
        expiresAt:
          type:
            - string
            - "null"
          format: date-time
        voidedReason:
          type:
            - string
            - "null"
          description: Why the contract was voided, when PE has a reason.
        declineReason:
          type:
            - string
            - "null"
          description: The reason the signer gave when declining.
        signers:
          type: array
          items:
            $ref: "#/components/schemas/ContractEsignSigner"
        testMode:
          type: boolean
        documentsRendered:
          type:
            - boolean
            - "null"
          description: "Test keys: whether PE rendered the contract PDF. null for production keys."
        documentsNotRenderedReason:
          type:
            - string
            - "null"
          description: "Test keys: why the PDF is missing."
        documents:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/ContractDocument"
          description: "Test keys: the rendered contract PDF. null for production keys."
    ContractEsignResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractEsign"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractResendRequest:
      type: object
      additionalProperties: false
      properties:
        assignedToEmail:
          type: string
          format: email
          maxLength: 254
          description: "The rep who sends (administrator or editor). Default: the X-PE-Actor-Email user."
    ContractVoidRequest:
      type: object
      additionalProperties: false
      required:
        - reason
      properties:
        reason:
          type: string
          minLength: 1
          maxLength: 500
          description: Why the contract is voided. PE records it.
    ContractVoidResult:
      type: object
      additionalProperties: false
      required:
        - projectId
        - packetId
        - status
        - previousStatus
        - voidedReason
      properties:
        projectId:
          type: string
        packetId:
          type: string
        status:
          type: string
          const: voided
        previousStatus:
          type: string
        voidedReason:
          type: string
    ContractVoidResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: "#/components/schemas/ContractVoidResult"
        meta:
          $ref: "#/components/schemas/Meta"
    ContractStatusChangedEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - createdAt
        - environment
        - data
      properties:
        id:
          type: string
          description: The event id (evt_...). Same as PE-Event-Id.
        type:
          type: string
          const: project.contract_status_changed
        createdAt:
          type: string
          format: date-time
        environment:
          $ref: "#/components/schemas/Environment"
        data:
          type: object
          additionalProperties: false
          required:
            - projectId
            - externalId
            - packetId
            - status
            - signers
            - occurredAt
          properties:
            projectId:
              type: string
            externalId:
              type:
                - string
                - "null"
            packetId:
              type: string
            status:
              $ref: "#/components/schemas/ContractStatus"
            signers:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                  - role
                  - status
                  - signedAt
                properties:
                  role:
                    type: string
                  status:
                    $ref: "#/components/schemas/SignerStatus"
                  signedAt:
                    type:
                      - string
                      - "null"
                    format: date-time
            occurredAt:
              type:
                - string
                - "null"
              format: date-time
              description: When the contract reached this state.
