# Participate Energy Installer API v2

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

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 id="contract-esign"></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.

## Endpoints

| Method and path | operationId | Scope | Actor header |
|---|---|---|---|
| `GET /ping` | `ping` | none | optional |
| `GET /me` | `getMe` | none | optional |
| `GET /avl` | `listAvl` | `avl:read` | optional |
| `GET /avl/{itemId}` | `getAvlItem` | `avl:read` | optional |
| `GET /safe-harbor/opportunities` | `listSafeHarborOpportunities` | `avl:read` | optional |
| `GET /safe-harbor/opportunities/{opportunityId}` | `getSafeHarborOpportunity` | `avl:read` | optional |
| `GET /utilities` | `listUtilities` | `avl:read` | optional |
| `GET /states` | `listStates` | `avl:read` | optional |
| `GET /equipment-map` | `getEquipmentMap` | `avl:read` | optional |
| `GET /reference` | `getReference` | `avl:read` | optional |
| `POST /eligibility` | `checkEligibility` | `eligibility:read` | optional |
| `POST /checks/domestic-content` | `checkDomesticContent` | `eligibility:read` | optional |
| `POST /checks/energy-community` | `checkEnergyCommunity` | `eligibility:read` | optional |
| `POST /checks/sales-tax` | `checkSalesTax` | `eligibility:read` | optional |
| `POST /pricing/lease` | `priceLease` | `pricing:lease` | optional |
| `GET /pricing/sungage/products` | `listSungageProducts` | `pricing:sungage` | required |
| `POST /pricing/sungage` | `priceSungage` | `pricing:sungage` | required |
| `POST /contract-uploads` | `createContractUpload` | `projects:create` | required |
| `POST /contract-uploads/{uploadId}/submit` | `submitContractUpload` | `projects:create` | required |
| `GET /contract-uploads/{uploadId}` | `getContractUpload` | `projects:create` | optional |
| `POST /contract-esign` | `createContractEsign` | `projects:create` | optional |
| `POST /contract-drafts` | `createContractDraft` | `contracts:write` | required |
| `GET /contract-drafts` | `listContractDrafts` | `contracts:write` | optional |
| `GET /contract-drafts/defaults` | `getContractDraftDefaults` | `contracts:write` | optional |
| `GET /contract-drafts/{draftId}` | `getContractDraft` | `contracts:write` | optional |
| `PATCH /contract-drafts/{draftId}` | `updateContractDraft` | `contracts:write` | required |
| `DELETE /contract-drafts/{draftId}` | `deleteContractDraft` | `contracts:write` | required |
| `POST /contract-drafts/{draftId}/validate` | `validateContractDraft` | `contracts:write` | optional |
| `POST /contract-drafts/{draftId}/send` | `sendContractDraft` | `contracts:send` | required |
| `GET /projects/{projectId}/contract-esign` | `getContractEsign` | `projects:read` | optional |
| `POST /projects/{projectId}/contract-esign/send` | `resendContractEsign` | `contracts:send` | required |
| `POST /projects/{projectId}/contract-esign/void` | `voidContractEsign` | `contracts:send` | required |
| `GET /projects` | `listProjects` | `projects:read` | optional |
| `GET /projects/by-external-id/{externalId}` | `getProjectByExternalId` | `projects:read` | optional |
| `GET /projects/{projectId}` | `getProject` | `projects:read` | optional |
| `PATCH /projects/{projectId}` | `updateProject` | `projects:write` | required |
| `PUT /projects/{projectId}/financials` | `updateProjectFinancials` | `projects:write` | required |
| `PUT /projects/{projectId}/equipment` | `updateProjectEquipment` | `projects:write` | required |
| `PUT /projects/{projectId}/safe-harbor` | `setProjectSafeHarbor` | `projects:write` | required |
| `GET /projects/{projectId}/activity` | `listProjectActivity` | `projects:read` | optional |
| `GET /projects/{projectId}/documents` | `listProjectDocuments` | `projects:read` | optional |
| `GET /projects/{projectId}/documents/{documentType}/versions/{version}/download` | `getDocumentDownloadUrl` | `projects:read` | optional |
| `POST /projects/{projectId}/documents/{documentType}/uploads` | `createDocumentUpload` | `documents:write` | required |
| `POST /projects/{projectId}/documents/{documentType}/uploads/{fileUploadId}/confirm` | `confirmDocumentUpload` | `documents:write` | required |
| `POST /projects/{projectId}/documents/{documentType}/versions/{version}/archive` | `archiveDocumentVersion` | `documents:write` | required |
| `POST /projects/{projectId}/documents/{documentType}/versions/{version}/restore` | `restoreDocumentVersion` | `documents:write` | required |
| `GET /projects/{projectId}/photos` | `listProjectPhotos` | `projects:read` | optional |
| `POST /projects/{projectId}/photos/{category}/uploads` | `createPhotoUpload` | `documents:write` | required |
| `POST /projects/{projectId}/photos/{category}/uploads/{batchId}/confirm` | `confirmPhotoUpload` | `documents:write` | required |
| `GET /projects/{projectId}/monitoring-access` | `getMonitoringAccess` | `projects:read` | optional |
| `PUT /projects/{projectId}/monitoring-access` | `setMonitoringAccess` | `documents:write` | required |
| `GET /projects/{projectId}/actions` | `listProjectActions` | `projects:read` | optional |
| `GET /projects/{projectId}/actions/{actionId}` | `getProjectAction` | `projects:read` | optional |
| `POST /projects/{projectId}/actions/{actionId}/resolve` | `resolveProjectAction` | `actions:write` | required |
| `POST /projects/{projectId}/actions/{actionId}/notes` | `addProjectActionNote` | `actions:write` | required |
| `GET /webhooks` | `getWebhook` | `webhooks:manage` | optional |
| `PUT /webhooks` | `setWebhook` | `webhooks:manage` | optional |
| `DELETE /webhooks` | `deleteWebhook` | `webhooks:manage` | optional |
| `POST /webhooks/rotate-secret` | `rotateWebhookSecret` | `webhooks:manage` | optional |
| `POST /webhooks/test` | `testWebhook` | `webhooks:manage` | optional |
| `POST /sandbox/projects/{projectId}/simulate` | `simulateProjectEvent` | `projects:read` | optional |
| `GET /sandbox/scenarios` | `listSandboxScenarios` | none | optional |

## Endpoint reference: Meta

### GET /ping

**Check the key.** operationId `ping`. Scope: none. X-PE-Actor-Email: optional.

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.

Response: HTTP 200, `data` is `Ping`.

```json
{
  "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"
  }
}
```

Errors: the common errors only.

### GET /me

**Read your account.** operationId `getMe`. Scope: none. X-PE-Actor-Email: optional.

Read your company's account facts: active states, enabled products, Sungage enrollment, the enabled environments and the rate limits for this key.

Response: HTTP 200, `data` is `Me`.

```json
{
  "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
    }
  }
}
```

Errors: the common errors only.

## Endpoint reference: Reference

### GET /avl

**List AVL equipment.** operationId `listAvl`. Scope: `avl:read`. X-PE-Actor-Email: optional.

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.

Query parameters: `category`, `manufacturer`, `q`, `updatedSince`, `limit`, `cursor`.

Response: HTTP 200, `data` is `AvlPage`.

```json
{
  "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
  }
}
```

Errors (besides the common errors): [`CURSOR_INVALID`](#error-CURSOR_INVALID).

### GET /avl/{itemId}

**Read an AVL item.** operationId `getAvlItem`. Scope: `avl:read`. X-PE-Actor-Email: optional.

Read one AVL item by its `avlItemId`.

Response: HTTP 200, `data` is `AvlItem`.

```json
{
  "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
    }
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### GET /safe-harbor/opportunities

**List Safe Harbor opportunities.** operationId `listSafeHarborOpportunities`. Scope: `avl:read`. X-PE-Actor-Email: optional.

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

Response: HTTP 200, `data` is `SafeHarborOpportunityList`.

```json
{
  "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
      }
    ]
  }
}
```

Errors: the common errors only.

### GET /safe-harbor/opportunities/{opportunityId}

**Read a Safe Harbor opportunity.** operationId `getSafeHarborOpportunity`. Scope: `avl:read`. X-PE-Actor-Email: optional.

Read one of your opportunities with its custom AVL. A project with equipment that matches the custom AVL uses its Domestic Content values.

Response: HTTP 200, `data` is `SafeHarborOpportunityDetail`.

```json
{
  "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
        }
      }
    ]
  }
}
```

Errors (besides the common errors): [`SAFE_HARBOR_OPPORTUNITY_NOT_FOUND`](#error-SAFE_HARBOR_OPPORTUNITY_NOT_FOUND), [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### GET /utilities

**List the utilities of a ZIP code.** operationId `listUtilities`. Scope: `avl:read`. X-PE-Actor-Email: optional.

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.

Query parameters: `zipCode` (required, 5 digits or ZIP+4; PE uses the first 5 digits).

Response: HTTP 200, `data` is `UtilityList`.

```json
{
  "data": {
    "zipCode": "78701",
    "stateCode": "TX",
    "utilities": [
      {
        "name": "Austin Energy",
        "primary": true
      }
    ]
  }
}
```

Errors: the common errors only.

### GET /states

**List your states.** operationId `listStates`. Scope: `avl:read`. X-PE-Actor-Email: optional.

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.

Response: HTTP 200, `data` is `StateList`.

```json
{
  "data": {
    "states": [
      {
        "stateCode": "CA",
        "name": "California"
      },
      {
        "stateCode": "TX",
        "name": "Texas"
      }
    ],
    "enabledProducts": [
      "Synthetic Cash"
    ]
  }
}
```

Errors: the common errors only.

### GET /equipment-map

**Read your Equipment Map.** operationId `getEquipmentMap`. Scope: `avl:read`. X-PE-Actor-Email: optional.

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

Query parameters: `category`, `field`, `q`, `limit`, `cursor`.

Response: HTTP 200, `data` is `EquipmentMapPage`.

```json
{
  "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
  }
}
```

Errors (besides the common errors): [`CURSOR_INVALID`](#error-CURSOR_INVALID).

### GET /reference

**Read the reference lists.** operationId `getReference`. Scope: `avl:read`. X-PE-Actor-Email: optional.

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.

Response: HTTP 200, `data` is `Reference`.

```json
{
  "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": []
  }
}
```

Errors: the common errors only.

## Endpoint reference: Eligibility

### POST /eligibility

**Check site eligibility.** operationId `checkEligibility`. Scope: `eligibility:read`. X-PE-Actor-Email: optional.

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.

Request body (`EligibilityRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `address` | object | yes | A US site address. |
| `address.street` | string | yes | The street line. 1 to 200 characters. |
| `address.city` | string | yes | 1 to 100 characters. |
| `address.stateCode` | string | yes | A 2-letter US state code. Pattern `^[A-Za-z]{2}$`. |
| `address.zipCode` | string | yes | 5 digits, or ZIP+4. Pattern `^\d{5}(-\d{4})?$`. |
| `homeType` | `single_family`, `townhome`, `condo`, `manufactured`, `multi_family`, `other` | no |  |
| `ownership` | `owner`, `renter` | no |  |
| `existingSolarOnProperty` | `none`, `add_to_existing`, `separate_system` | no |  |
| `utility` | string | no | The utility name. See GET /utilities. 1 to 200 characters. |
| `systemType` | `solar_only`, `solar_battery`, `battery_only` | yes |  |

```json
{
  "address": {
    "street": "100 Example Street",
    "city": "Austin",
    "stateCode": "TX",
    "zipCode": "78701"
  },
  "homeType": "townhome",
  "ownership": "owner",
  "existingSolarOnProperty": "none",
  "utility": "Austin Energy",
  "systemType": "solar_battery"
}
```

Response: HTTP 200, `data` is `Eligibility`.

```json
{
  "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."
      }
    ]
  }
}
```

Errors (besides the common errors): [`ADDRESS_OUTSIDE_US`](#error-ADDRESS_OUTSIDE_US), [`ADDRESS_PO_BOX`](#error-ADDRESS_PO_BOX).

### POST /checks/domestic-content

**Check Domestic Content.** operationId `checkDomesticContent`. Scope: `eligibility:read`. X-PE-Actor-Email: optional.

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. Each item also has `feocPercent`.

Request body (`DomesticContentRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `equipment` | array of objects | yes | 1 to 50 items. |
| `equipment[].sku` | string | yes | 1 to 120 characters. |
| `equipment[].category` | `bess`, `pv_module`, `pv_combo`, `pv_inverter`, `pv_racking`, `pv_railing`, `pv_fasteners` | yes | An equipment category. |
| `equipment[].quantity` | integer | no | 1 to 10000. |
| `year` | integer | no | The year for the Domestic Content and FEOC thresholds. Default: this year. A Safe Harbor beginning of construction date wins over it. 2025 to 2035. |
| `safeHarborOpportunityId` | string | no | Include this opportunity's custom AVL. 1 to 64 characters. |

```json
{
  "equipment": [
    {
      "sku": "Q.TRON BLK M-G2+ 430",
      "category": "pv_module",
      "quantity": 20
    },
    {
      "sku": "IQ8M-72-2-US",
      "category": "pv_inverter",
      "quantity": 20
    }
  ]
}
```

Response: HTTP 200, `data` is `DomesticContent`.

```json
{
  "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."
      }
    ]
  }
}
```

Errors (besides the common 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).

### POST /checks/energy-community

**Check Energy Community.** operationId `checkEnergyCommunity`. Scope: `eligibility:read`. X-PE-Actor-Email: optional.

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.

Request body (`EnergyCommunityRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `address` | object | yes | A US site address. |
| `address.street` | string | yes | The street line. 1 to 200 characters. |
| `address.city` | string | yes | 1 to 100 characters. |
| `address.stateCode` | string | yes | A 2-letter US state code. Pattern `^[A-Za-z]{2}$`. |
| `address.zipCode` | string | yes | 5 digits, or ZIP+4. Pattern `^\d{5}(-\d{4})?$`. |

```json
{
  "address": {
    "street": "100 Example Street",
    "city": "Sacramento",
    "stateCode": "CA",
    "zipCode": "95814"
  }
}
```

Response: HTTP 200, `data` is `EnergyCommunity`.

```json
{
  "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
    }
  }
}
```

`resolvedAddress` (`ResolvedAddress`) is the address PE found with Google Maps:

| Field | Type | Notes |
|---|---|---|
| `formatted` | string | The full address as Google Maps writes it. |
| `street` | string | The street number and the street name. When `precision` is `street`, the street line you sent. |
| `city` | string or null | The city. Null when Google returned no city. |
| `stateCode` | string | The 2-letter state code. |
| `zipCode` | string or null | The 5-digit ZIP code. Null when Google returned no ZIP code. |
| `county` | string or null | The county name, without the word County. |
| `latitude`, `longitude` | number | The point Google placed. |
| `precision` | `rooftop`, `interpolated`, `street` | `rooftop`: on the building. `interpolated`: between two known street numbers on the street. `street`: Google placed the street but not the house number. Only the sales tax check returns `street`, and only outside Colorado. |
| `partialMatch` | boolean | Google matched only part of the address you sent. Compare this address with your address before you use the result. |

Errors (besides the common 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).

### POST /checks/sales-tax

**Read the lease sales tax rate.** operationId `checkSalesTax`. Scope: `eligibility:read`. X-PE-Actor-Email: optional.

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.

`jurisdiction.lowConfidence` is true when PE is not sure of the jurisdiction: the ZIP code has more than one rate and PE used the most common one, Google only partially matched the address (`resolvedAddress.partialMatch`), Google placed only the street and not the house number (`resolvedAddress.precision` is `street`), or the Colorado state lookup placed the address only approximately.

Request body (`SalesTaxCheckRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `address` | object | yes | A US site address. |
| `address.street` | string | yes | The street line. 1 to 200 characters. |
| `address.city` | string | yes | 1 to 100 characters. |
| `address.stateCode` | string | yes | A 2-letter US state code. Pattern `^[A-Za-z]{2}$`. |
| `address.zipCode` | string | yes | 5 digits, or ZIP+4. Pattern `^\d{5}(-\d{4})?$`. |
| `systemType` | `solar_only`, `solar_battery`, `battery_only` | yes |  |
| `existingSolarOnProperty` | boolean | no | Battery_only: the property already has solar. It changes the tax in some states. |
| `contractDate` | string | no | YYYY-MM-DD. Default: today in America/Los_Angeles. Format date. |
| `netAmountDue` | number | no | 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. |

```json
{
  "address": {
    "street": "200 Example Avenue",
    "city": "Austin",
    "stateCode": "TX",
    "zipCode": "78701"
  },
  "systemType": "solar_only",
  "netAmountDue": 21000
}
```

Response: HTTP 200, `data` is `SalesTaxCheck`.

```json
{
  "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
    }
  }
}
```

`resolvedAddress` has the same fields as in `POST /checks/energy-community`.

Errors (besides the common 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).

## Endpoint reference: Pricing

### POST /pricing/lease

**Price a PE lease.** operationId `priceLease`. Scope: `pricing:lease`. X-PE-Actor-Email: optional.

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.

Every quote has `warnings`, an empty array when there is none. A warning never stops the quote: `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), `FIELD_NOT_APPLICABLE` (a flag that does not apply to the system type), `STATE_NOT_ACTIVE_FOR_INSTALLER` and `SALES_TAX_NEEDS_ATTENTION`. Each warning has `code`, `message` and, for the v2.2 codes, `field`.

Request body (`LeasePriceRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `epcAmount` | number | no | 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` | number | no | Roofing under the array, in USD. Default 0. |
| `ineligibleRoofingCost` | number | no | Other roofing, in USD. Default 0. |
| `systemType` | `solar_only`, `solar_battery`, `battery_only` | yes |  |
| `insuranceOption` | `1`, `2`, `3` | yes | The homeowner's insurance option. See How PE prices a lease. The string "1", "2" or "3" is accepted too. |
| `address` | object | yes | A US site address. |
| `address.street` | string | yes | The street line. 1 to 200 characters. |
| `address.city` | string | yes | 1 to 100 characters. |
| `address.stateCode` | string | yes | A 2-letter US state code. Pattern `^[A-Za-z]{2}$`. |
| `address.zipCode` | string | yes | 5 digits, or ZIP+4. Pattern `^\d{5}(-\d{4})?$`. |
| `pvDomesticContent` | boolean | yes | The PV equipment meets Domestic Content. |
| `storageDomesticContent` | boolean | yes | The storage equipment meets Domestic Content. |
| `energyCommunity` | boolean or `auto` | yes | True, false, or "auto" to run the Energy Community check on the address. |
| `dcBonusRecipient` | `installer`, `customer` | yes | Who gets the Domestic Content bonus at the 35% tier. Any case is accepted. |
| `systemSizeKw` | number | no | 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` | object | no |  |
| `includedIncentive.type` | `none`, `hawaii_retitc`, `installer_managed` | yes |  |
| `includedIncentive.amount` | number | no | Installer_managed only: the amount in USD. |
| `safeHarbor` | object | no |  |
| `safeHarbor.opportunityId` | string | yes | From GET /safe-harbor/opportunities. |
| `safeHarbor.units` | integer | yes | Whole units, from 1 to the units available. |
| `existingSolarOnProperty` | boolean | no | Battery_only: the property already has solar. It changes the sales tax in some states. |
| `contractDate` | string | no | 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` | `epc`, `netAmountDue` | no | Price from the EPC (default) or solve the EPC from targetNetAmountDue. |
| `targetNetAmountDue` | number | no | 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`). |

```json
{
  "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"
}
```

Response: HTTP 200, `data` is `LeasePriceQuote`.

Errors (besides the common 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).

### GET /pricing/sungage/products

**List Sungage products.** operationId `listSungageProducts`. Scope: `pricing:sungage`. X-PE-Actor-Email: required.

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.

Query parameters: `stateCode` (required).

Response: HTTP 200, `data` is `SungageProducts`.

```json
{
  "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
              }
            ]
          }
        ]
      }
    ]
  }
}
```

Errors (besides the common 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).

### POST /pricing/sungage

**Price a PE lease with a Sungage loan.** operationId `priceSungage`. Scope: `pricing:sungage`. X-PE-Actor-Email: required.

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.

Request body (`SungagePriceRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `epcAmount` | number | yes | The total EPC before tax, in USD: 1,000 to 500,000 (v2.2). |
| `eligibleRoofingCost` | number | no | Roofing under the array, in USD. Default 0. |
| `ineligibleRoofingCost` | number | no | Other roofing, in USD. Default 0. |
| `systemType` | `solar_only`, `solar_battery`, `battery_only` | yes |  |
| `insuranceOption` | `1`, `2`, `3` | yes | The homeowner's insurance option. See How PE prices a lease. The string "1", "2" or "3" is accepted too. |
| `address` | object | yes | A US site address. |
| `address.street` | string | yes | The street line. 1 to 200 characters. |
| `address.city` | string | yes | 1 to 100 characters. |
| `address.stateCode` | string | yes | A 2-letter US state code. Pattern `^[A-Za-z]{2}$`. |
| `address.zipCode` | string | yes | 5 digits, or ZIP+4. Pattern `^\d{5}(-\d{4})?$`. |
| `pvDomesticContent` | boolean | yes | The PV equipment meets Domestic Content. |
| `storageDomesticContent` | boolean | yes | The storage equipment meets Domestic Content. |
| `energyCommunity` | boolean or `auto` | yes | True, false, or "auto" to run the Energy Community check on the address. |
| `dcBonusRecipient` | `installer`, `customer` | yes | Who gets the Domestic Content bonus at the 35% tier. Any case is accepted. |
| `systemSizeKw` | number | no | 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` | object | no |  |
| `includedIncentive.type` | `none`, `hawaii_retitc`, `installer_managed` | yes |  |
| `includedIncentive.amount` | number | no | Installer_managed only: the amount in USD. |
| `safeHarbor` | object | no |  |
| `safeHarbor.opportunityId` | string | yes | From GET /safe-harbor/opportunities. |
| `safeHarbor.units` | integer | yes | Whole units, from 1 to the units available. |
| `existingSolarOnProperty` | boolean | no | Battery_only: the property already has solar. It changes the sales tax in some states. |
| `contractDate` | string | no | 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` | `Installment`, `Classic DPP`, `Escalator` | yes |  |
| `term` | `5`, `10`, `15`, `20`, `25`, `30` | yes | Years. At most 25, and at most 10 for battery_only. |
| `rate` | number | yes | The loan rate in percent, from GET /pricing/sungage/products. At least 0. |

```json
{
  "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
}
```

Response: HTTP 200, `data` is `SungageQuote`.

Errors (besides the common 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).

## Endpoint reference: Contract uploads

### POST /contract-uploads

**Create a contract upload.** operationId `createContractUpload`. Scope: `projects:create`. X-PE-Actor-Email: required.

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.

Request body (`CreateContractUploadRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `stateCode` | string | yes | The 2-letter state of the site. Pattern `^[A-Za-z]{2}$`. |
| `productType` | `Synthetic Cash`, `Distributed Microgrid` | no | Default: Synthetic Cash. The API creates Synthetic Cash projects only: Distributed Microgrid returns PRODUCT_NOT_SUPPORTED_BY_API. |
| `externalId` | string | no | Your id for the project: letters, digits, - and _. Spaces around it are trimmed. 1 to 128 characters. Pattern `^[A-Za-z0-9_-]{1,128}$`. |
| `salesRep` | object | no |  |
| `salesRep.name` | string | no | 1 to 200 characters. |
| `salesRep.email` | string | no | At most 254 characters. Format email. |
| `fileName` | string | yes | The file name. It must end in .pdf and have no slashes. At most 200 characters. Pattern `\.[pP][dD][fF]$`. |
| `sandboxScenario` | `project_created`, `project_created_action_required`, `draft_failed_basic_tests`, `draft_invalid_document`, `draft_duplicate`, `product_mismatch`, `canon_rejected`, `sibyl_error` | no | A Test contract upload scenario. Default project_created. |

```json
{
  "stateCode": "CA",
  "externalId": "crm-10442",
  "salesRep": {
    "name": "Riley Rep",
    "email": "riley@installer.example"
  },
  "fileName": "jordan-example-agreement.pdf",
  "sandboxScenario": "project_created"
}
```

Response: HTTP 201, `data` is `CreatedContractUpload`.

```json
{
  "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"
  }
}
```

Errors (besides the common 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).

### POST /contract-uploads/{uploadId}/submit

**Submit a contract upload.** operationId `submitContractUpload`. Scope: `projects:create`. X-PE-Actor-Email: required.

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.

Response: HTTP 202, `data` is `SubmittedContractUpload`.

```json
{
  "data": {
    "uploadId": "iup_9Bv4Nc7Xz2Lk5Hj8Gf3D",
    "status": "queued"
  }
}
```

Errors (besides the common 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).

### GET /contract-uploads/{uploadId}

**Read a contract upload.** operationId `getContractUpload`. Scope: `projects:create`. X-PE-Actor-Email: optional.

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

Response: HTTP 200, `data` is `ContractUpload`.

```json
{
  "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"
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### POST /contract-esign

**Replaced: use the contract draft send.** operationId `createContractEsign`. Scope: `projects:create`. X-PE-Actor-Email: optional.

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

Errors (besides the common errors): [`CONTRACT_ESIGN_MOVED`](#error-CONTRACT_ESIGN_MOVED).

## Endpoint reference: Contract drafts

### GET /contract-drafts

**List contract drafts.** operationId `listContractDrafts`. Scope: `contracts:write`. X-PE-Actor-Email: optional.

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.

Query parameters: `limit`, `cursor`, `externalId`, `assignedToEmail`, `status`.

Errors (besides the common errors): [`CURSOR_INVALID`](#error-CURSOR_INVALID).

### POST /contract-drafts

**Create a contract draft.** operationId `createContractDraft`. Scope: `contracts:write`. X-PE-Actor-Email: required.

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.

Query parameters: `dryRun`.

Request body: see The draft body in Contract drafts and e-sign.

Errors (besides the common 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).

### GET /contract-drafts/defaults

**Read your prefill for a state.** operationId `getContractDraftDefaults`. Scope: `contracts:write`. X-PE-Actor-Email: optional.

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

Query parameters: `stateCode` (required), `utility` (optional, the utility name; see the Contract drafts section).

Errors: only the common errors.

### GET /contract-drafts/{draftId}

**Read a contract draft.** operationId `getContractDraft`. Scope: `contracts:write`. X-PE-Actor-Email: optional.

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.

Errors (besides the common errors): [`DRAFT_NOT_FOUND`](#error-DRAFT_NOT_FOUND).

### PATCH /contract-drafts/{draftId}

**Update a contract draft.** operationId `updateContractDraft`. Scope: `contracts:write`. X-PE-Actor-Email: required.

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.

Request body: see The draft body in Contract drafts and e-sign.

Errors (besides the common 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).

### DELETE /contract-drafts/{draftId}

**Delete a contract draft.** operationId `deleteContractDraft`. Scope: `contracts:write`. X-PE-Actor-Email: required.

Delete the draft. Refused once it is being sent or was sent.

Errors (besides the common errors): [`DRAFT_NOT_FOUND`](#error-DRAFT_NOT_FOUND), [`DRAFT_ALREADY_SENT`](#error-DRAFT_ALREADY_SENT), [`DRAFT_SEND_IN_PROGRESS`](#error-DRAFT_SEND_IN_PROGRESS).

### POST /contract-drafts/{draftId}/validate

**Validate a contract draft.** operationId `validateContractDraft`. Scope: `contracts:write`. X-PE-Actor-Email: optional.

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.

Errors (besides the common errors): [`DRAFT_NOT_FOUND`](#error-DRAFT_NOT_FOUND).

### POST /contract-drafts/{draftId}/send

**Send a contract draft for e-signature.** operationId `sendContractDraft`. Scope: `contracts:send`. X-PE-Actor-Email: required.

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.

Errors (besides the common 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).

## Endpoint reference: Contract e-sign

### GET /projects/{projectId}/contract-esign

**Read the project's contract.** operationId `getContractEsign`. Scope: `projects:read`. X-PE-Actor-Email: optional.

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.

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PACKET_NOT_FOUND`](#error-PACKET_NOT_FOUND).

### POST /projects/{projectId}/contract-esign/send

**Send the project's contract again.** operationId `resendContractEsign`. Scope: `contracts:send`. X-PE-Actor-Email: required.

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.

Request body (optional): `assignedToEmail`, the rep who sends.

Errors (besides the common 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).

### POST /projects/{projectId}/contract-esign/void

**Void the project's contract.** operationId `voidContractEsign`. Scope: `contracts:send`. X-PE-Actor-Email: required.

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.

Request body: `reason` (required).

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PACKET_NOT_FOUND`](#error-PACKET_NOT_FOUND), [`PACKET_NOT_VOIDABLE`](#error-PACKET_NOT_VOIDABLE).

## Endpoint reference: Projects

### GET /projects

**List your projects.** operationId `listProjects`. Scope: `projects:read`. X-PE-Actor-Email: optional.

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.

Query parameters: `externalId`, `status`, `milestone`, `updatedSince`, `limit`, `cursor`.

Response: HTTP 200, `data` is `ProjectList`.

```json
{
  "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"
  }
}
```

Errors (besides the common errors): [`CURSOR_INVALID`](#error-CURSOR_INVALID).

### GET /projects/by-external-id/{externalId}

**Read a project by external ID.** operationId `getProjectByExternalId`. Scope: `projects:read`. X-PE-Actor-Email: optional.

Read a project by your own id. The response is the same as `GET /projects/{projectId}`.

Response: HTTP 200, `data` is `ProjectDetail`.

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`EXTERNAL_ID_AMBIGUOUS`](#error-EXTERNAL_ID_AMBIGUOUS).

### GET /projects/{projectId}

**Read a project.** operationId `getProject`. Scope: `projects:read`. X-PE-Actor-Email: optional.

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

Response: HTTP 200, `data` is `ProjectDetail`.

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### PATCH /projects/{projectId}

**Update project fields.** operationId `updateProject`. Scope: `projects:write`. X-PE-Actor-Email: required.

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.

Query parameters: `dryRun`.

Request body (`ProjectPatchRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `expectedUpdatedAt` | string | no | The updatedAt you read. PE refuses the change if the project changed after it. Format date-time. |
| `customer` | object | no |  |
| `customer.firstName` | string | no | 1 to 100 characters. |
| `customer.lastName` | string | no | 1 to 100 characters. |
| `customer.email` | string | no | At most 254 characters. Format email. |
| `customer.phone` | string | no | Digits, spaces, +, -, ( and ). 7 to 30 characters. PE stores a 10-digit US number as (NNN) NNN-NNNN, so a read returns that form. |
| `cosigner` | object | no |  |
| `cosigner.firstName` | string | no | 1 to 100 characters. |
| `cosigner.lastName` | string | no | 1 to 100 characters. |
| `cosigner.email` | string | no | At most 254 characters. Format email. |
| `cosigner.phone` | string | no | Digits, spaces, +, -, ( and ). 7 to 30 characters. PE stores a 10-digit US number as (NNN) NNN-NNNN, so a read returns that form. |
| `mailingAddress` | object | no |  |
| `mailingAddress.sameAsSite` | boolean | yes |  |
| `mailingAddress.street` | string | no | 1 to 200 characters. |
| `mailingAddress.city` | string | no | 1 to 100 characters. |
| `mailingAddress.state` | string | no | 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}$`. |
| `mailingAddress.zipCode` | string | no | 5 digits or ZIP+4. PE stores the 5 digits. Pattern `^\d{5}(-\d{4})?$`. |
| `utility` | object | no |  |
| `utility.name` | string | no | A name from GET /utilities. 1 to 200 characters. |
| `utility.meterId` | string | no | 1 to 64 characters. |
| `utility.nameOnBill` | string | no | 1 to 200 characters. |
| `salesRep` | object | no |  |
| `salesRep.name` | string | no | 1 to 100 characters. |
| `salesRep.email` | string | no | At most 254 characters. Format email. |
| `externalId` | string or null | no | Your id: 1 to 128 letters, digits, - and _. Null clears it. At most 128 characters. |

```json
{
  "expectedUpdatedAt": "2026-11-10T21:14:55.000Z",
  "customer": {
    "phone": "555-010-0123"
  },
  "utility": {
    "meterId": "1009988776"
  }
}
```

Response: HTTP 200, `data` is `ProjectUpdateResult`.

Errors (besides the common 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).

### PUT /projects/{projectId}/financials

**Update the financials.** operationId `updateProjectFinancials`. Scope: `projects:write`. X-PE-Actor-Email: required.

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.

Query parameters: `dryRun`.

Request body (`FinancialsRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `expectedUpdatedAt` | string | no | Format date-time. |
| `basis` | `epc`, `netAmountDue` | yes |  |
| `epcAmount` | number | no | Basis epc only. The total EPC in USD: 1,000 to 500,000 (outside it `EPC_OUT_OF_RANGE`). |
| `targetNetAmountDue` | number | no | Basis netAmountDue only. 1,000 to 500,000 USD (outside it `EPC_OUT_OF_RANGE`). |
| `eligibleRoofingCost` | number | no | 0 to 10000000. |
| `ineligibleRoofingCost` | number | no | 0 to 10000000. |
| `insuranceOption` | `1`, `2`, `3` | no | Stored and returned as "1", "2" or "3". The number 1, 2 or 3 (the pricing form) is accepted too. |
| `dcBonusRecipient` | `Installer`, `Customer` | no | Stored and returned as Installer or Customer. Any case is accepted, including the pricing form. |
| `lender` | string or null | no | 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. 1 to 100 characters. |
| `amountFinancedByLender` | boolean | no |  |

```json
{
  "basis": "epc",
  "epcAmount": 31500,
  "eligibleRoofingCost": 2000,
  "ineligibleRoofingCost": 6000,
  "insuranceOption": "1"
}
```

Response: HTTP 200, `data` is `FinancialsResult`.

```json
{
  "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
    }
  }
}
```

Errors (besides the common 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).

### PUT /projects/{projectId}/equipment

**Update the equipment.** operationId `updateProjectEquipment`. Scope: `projects:write`. X-PE-Actor-Email: required.

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.

Query parameters: `dryRun`.

Request body (`EquipmentRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `expectedUpdatedAt` | string | no | Format date-time. |
| `items` | array of objects | yes | One item per category. 1 to 6 items. |
| `items[].category` | `acModule`, `module`, `inverter`, `racking`, `battery`, `batteryExpansion` | yes | A project equipment category. acModule is an AC module (a module with a built-in inverter). |
| `items[].avlItemId` | string | no | An AVL item id. Send avlItemId or name. At most 128 characters. Pattern `^[A-Za-z0-9_-]+$`. |
| `items[].name` | string | no | The exact AVL string, or a string on your Equipment Map. Send avlItemId or name. 1 to 200 characters. |
| `items[].quantity` | integer | no | 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). 1 to 10000. |
| `systemSizeKw` | number | no | 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`); with a module count and no known wattage it must be possible at 250 W to 1,000 W per module. Leave it out to let PE compute it. |

```json
{
  "items": [
    {
      "category": "module",
      "avlItemId": "avl_8Hc2Kd91LmQ4",
      "quantity": 20
    },
    {
      "category": "inverter",
      "name": "Enphase - IQ8M-72-2-US",
      "quantity": 20
    }
  ]
}
```

Response: HTTP 200, `data` is `EquipmentResult`.

```json
{
  "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
        }
      ]
    }
  }
}
```

Errors (besides the common 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).

### PUT /projects/{projectId}/safe-harbor

**Link a Safe Harbor opportunity.** operationId `setProjectSafeHarbor`. Scope: `projects:write`. X-PE-Actor-Email: required.

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.

Query parameters: `dryRun`.

Request body (`SafeHarborRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `expectedUpdatedAt` | string | no | Format date-time. |
| `opportunityId` | string or null | yes | An opportunityId from GET /safe-harbor/opportunities. Null unlinks the opportunity. At most 64 characters. Pattern `^[A-Za-z0-9._-]+$`. |

```json
{
  "opportunityId": "SHO-0042"
}
```

Response: HTTP 200, `data` is `SafeHarborResult`.

Errors (besides the common 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).

### GET /projects/{projectId}/activity

**List the activity of a project.** operationId `listProjectActivity`. Scope: `projects:read`. X-PE-Actor-Email: optional.

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.

Query parameters: `limit`, `cursor`.

Response: HTTP 200, `data` is `ActivityPage`.

```json
{
  "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
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`CURSOR_INVALID`](#error-CURSOR_INVALID).

## Endpoint reference: Documents

### GET /projects/{projectId}/documents

**List the documents of a project.** operationId `listProjectDocuments`. Scope: `projects:read`. X-PE-Actor-Email: optional.

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.

Response: HTTP 200, `data` is `DocumentList`.

```json
{
  "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": []
      }
    ]
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### GET /projects/{projectId}/documents/{documentType}/versions/{version}/download

**Get a download URL.** operationId `getDocumentDownloadUrl`. Scope: `projects:read`. X-PE-Actor-Email: optional.

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

Response: HTTP 200, `data` is `DocumentDownload`.

```json
{
  "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"
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### POST /projects/{projectId}/documents/{documentType}/uploads

**Create a document upload.** operationId `createDocumentUpload`. Scope: `documents:write`. X-PE-Actor-Email: required.

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

Request body (`CreateDocumentUploadRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `fileName` | string | yes | 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`. 1 to 200 characters. |
| `contentType` | `application/pdf`, `image/jpeg`, `image/png`, `image/heic`, `image/heif` | yes | The file type. |

```json
{
  "fileName": "final-permit.pdf",
  "contentType": "application/pdf"
}
```

Response: HTTP 201, `data` is `CreatedDocumentUpload`.

```json
{
  "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"
  }
}
```

Errors (besides the common 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).

### POST /projects/{projectId}/documents/{documentType}/uploads/{fileUploadId}/confirm

**Confirm a document upload.** operationId `confirmDocumentUpload`. Scope: `documents:write`. X-PE-Actor-Email: required.

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.

Request body (`ConfirmUploadRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `notes` | string | no | A note for the reviewer. 1 to 2000 characters. |
| `resolveActionIds` | array of string | no | The open Actions this upload answers. An id that cannot be an Action id (for example one with a `/`) is returned in `skippedActionIds`. At most 20 items. |

```json
{
  "notes": "Corrected permit with the inspector's signature.",
  "resolveActionIds": [
    "act_7Gm2Qp9xVb4"
  ]
}
```

Response: HTTP 200, `data` is `ConfirmedDocumentUpload`.

```json
{
  "data": {
    "projectId": "CA2611-SMIT1",
    "documentType": "signedFinalPermit",
    "fileUploadId": "ifu_Q8w2Er5Ty7Ui9Op1As3D",
    "version": 2,
    "reviewStatus": "Pending Review",
    "reviewQueued": true,
    "resolvedActionIds": [
      "act_7Gm2Qp9xVb4"
    ],
    "skippedActionIds": []
  }
}
```

Errors (besides the common 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).

### POST /projects/{projectId}/documents/{documentType}/versions/{version}/archive

**Archive a document version.** operationId `archiveDocumentVersion`. Scope: `documents:write`. X-PE-Actor-Email: required.

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

Request body (`ArchiveRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `reason` | string | no | Why the version is archived. 1 to 500 characters. |

```json
{
  "reason": "Uploaded to the wrong project."
}
```

Response: HTTP 200, `data` is `ArchiveResult`.

```json
{
  "data": {
    "projectId": "CA2611-SMIT1",
    "documentType": "utilityBill",
    "version": 1,
    "archived": true,
    "changed": true,
    "currentChanged": true
  }
}
```

Errors (besides the common 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).

### POST /projects/{projectId}/documents/{documentType}/versions/{version}/restore

**Restore a document version.** operationId `restoreDocumentVersion`. Scope: `documents:write`. X-PE-Actor-Email: required.

Restore an archived version.

Request body (`ArchiveRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `reason` | string | no | Why the version is archived. 1 to 500 characters. |

```json
{}
```

Response: HTTP 200, `data` is `ArchiveResult`.

```json
{
  "data": {
    "projectId": "CA2611-SMIT1",
    "documentType": "utilityBill",
    "version": 1,
    "archived": false,
    "changed": true,
    "currentChanged": true
  }
}
```

Errors (besides the common 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).

## Endpoint reference: Photos

### GET /projects/{projectId}/photos

**List the photos of a project.** operationId `listProjectPhotos`. Scope: `projects:read`. X-PE-Actor-Email: optional.

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.

Response: HTTP 200, `data` is `PhotoList`.

```json
{
  "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": []
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### POST /projects/{projectId}/photos/{category}/uploads

**Create a photo upload.** operationId `createPhotoUpload`. Scope: `documents:write`. X-PE-Actor-Email: required.

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.

Request body (`CreatePhotoUploadRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `files` | array of objects | yes | 1 to 25 items. |
| `files[].fileName` | string | yes | 1 to 200 characters. |
| `files[].contentType` | `application/pdf`, `image/jpeg`, `image/png`, `image/heic`, `image/heif`, `image/webp`, `image/gif` | yes |  |

```json
{
  "files": [
    {
      "fileName": "racking-1.jpg",
      "contentType": "image/jpeg"
    },
    {
      "fileName": "racking-2.jpg",
      "contentType": "image/jpeg"
    }
  ]
}
```

Response: HTTP 201, `data` is `CreatedPhotoUpload`.

```json
{
  "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"
  }
}
```

Errors (besides the common 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).

### POST /projects/{projectId}/photos/{category}/uploads/{batchId}/confirm

**Confirm a photo upload.** operationId `confirmPhotoUpload`. Scope: `documents:write`. X-PE-Actor-Email: required.

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.

Request body (`ConfirmUploadRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `notes` | string | no | A note for the reviewer. 1 to 2000 characters. |
| `resolveActionIds` | array of string | no | The open Actions this upload answers. An id that cannot be an Action id (for example one with a `/`) is returned in `skippedActionIds`. At most 20 items. |

```json
{
  "notes": "Racking labels and mill marks."
}
```

Response: HTTP 200, `data` is `ConfirmedPhotoUpload`.

```json
{
  "data": {
    "projectId": "CA2611-SMIT1",
    "category": "racking",
    "batchId": "ifu_P0o9I8u7Y6t5R4e3W2q1",
    "uploaded": 2,
    "versions": [
      3,
      4
    ],
    "deduped": 0,
    "sectionsMissing": [],
    "reviewStatus": "Pending Review",
    "reviewQueued": false,
    "resolvedActionIds": [],
    "skippedActionIds": []
  }
}
```

Errors (besides the common 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).

## Endpoint reference: Monitoring access

### GET /projects/{projectId}/monitoring-access

**Read monitoring access.** operationId `getMonitoringAccess`. Scope: `projects:read`. X-PE-Actor-Email: optional.

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.

Response: HTTP 200, `data` is `MonitoringAccess`.

```json
{
  "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"
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### PUT /projects/{projectId}/monitoring-access

**Save monitoring site IDs.** operationId `setMonitoringAccess`. Scope: `documents:write`. X-PE-Actor-Email: required.

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.

Request body (`MonitoringAccessRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `sites` | array of objects | yes | All the sites of the project. At most 10 items. |
| `sites[].provider` | `tesla`, `enphase`, `solaredge`, `lunar`, `qcells`, `other` | yes | A monitoring provider. |
| `sites[].manufacturer` | string | no | 1 to 100 characters. |
| `sites[].siteId` | string | yes | 1 to 200 characters. |
| `verify` | `now`, `offline` | no | Default now. |
| `baseSitesHash` | string | no | 1 to 128 characters. |
| `resolveActionIds` | array of string | no | At most 20 items. |

```json
{
  "sites": [
    {
      "provider": "enphase",
      "siteId": "4410023"
    }
  ],
  "verify": "now",
  "baseSitesHash": "b1946ac92492d2347c6235b4d2611184"
}
```

Response: HTTP 200, `data` is `MonitoringAccessResult`.

```json
{
  "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"
    }
  }
}
```

Errors (besides the common 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).

## Endpoint reference: Actions

### GET /projects/{projectId}/actions

**List the Actions of a project.** operationId `listProjectActions`. Scope: `projects:read`. X-PE-Actor-Email: optional.

List the Actions of the project, newest first, with their notes and history. Filter by `status`.

Query parameters: `status`, `limit`.

Response: HTTP 200, `data` is `ActionList`.

```json
{
  "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
    }
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### GET /projects/{projectId}/actions/{actionId}

**Read an Action.** operationId `getProjectAction`. Scope: `projects:read`. X-PE-Actor-Email: optional.

Read one Action with its notes and history.

Response: HTTP 200, `data` is `ActionResponse`.

```json
{
  "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"
        }
      ]
    }
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND).

### POST /projects/{projectId}/actions/{actionId}/resolve

**Resolve an Action.** operationId `resolveProjectAction`. Scope: `actions:write`. X-PE-Actor-Email: required.

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

Request body (`NoteRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `note` | string | yes | 1 to 2000 characters. |

```json
{
  "note": "The customer initialed page 3. The new agreement is uploaded as version 2."
}
```

Response: HTTP 200, `data` is `ActionResolveResult`.

```json
{
  "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"
        }
      ]
    }
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED).

### POST /projects/{projectId}/actions/{actionId}/notes

**Add a note to an Action.** operationId `addProjectActionNote`. Scope: `actions:write`. X-PE-Actor-Email: required.

Add a note to an Action without a status change. Notes cannot be changed or deleted.

Request body (`NoteRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `note` | string | yes | 1 to 2000 characters. |

```json
{
  "note": "We asked the customer to sign again. Expected on Friday."
}
```

Response: HTTP 201, `data` is `ActionResponse`.

```json
{
  "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"
        }
      ]
    }
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`PROJECT_CANCELLED`](#error-PROJECT_CANCELLED).

## Endpoint reference: Webhooks

### GET /webhooks

**Read the webhook URL.** operationId `getWebhook`. Scope: `webhooks:manage`. X-PE-Actor-Email: optional.

Read the webhook URL of the key's environment. `url` is null when none is set.

Response: HTTP 200, `data` is `Webhook`.

```json
{
  "data": {
    "url": "https://crm.installer.example/pe/webhooks",
    "events": [
      "project.ic_approved",
      "project.pc_approved",
      "project.action_created"
    ],
    "secretVersion": 1
  }
}
```

Errors: the common errors only.

### PUT /webhooks

**Set the webhook URL.** operationId `setWebhook`. Scope: `webhooks:manage`. X-PE-Actor-Email: optional.

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.

Request body (`SetWebhookRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | An https URL on port 443 with a public host. 1 to 2048 characters. Format uri. |

```json
{
  "url": "https://crm.installer.example/pe/webhooks"
}
```

Response: HTTP 200, `data` is `WebhookWithSecret`.

```json
{
  "data": {
    "url": "https://crm.installer.example/pe/webhooks",
    "events": [
      "project.ic_approved",
      "project.pc_approved",
      "project.action_created"
    ],
    "secretVersion": 1,
    "signingSecret": "whsec_exampleSecretValueShownOnce"
  }
}
```

Errors (besides the common 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).

### DELETE /webhooks

**Delete the webhook URL.** operationId `deleteWebhook`. Scope: `webhooks:manage`. X-PE-Actor-Email: optional.

Stop webhooks in the key's environment. A later `PUT /webhooks` starts a new subscription with a new secret, from that moment.

Response: HTTP 200, `data` is `WebhookDeleted`.

```json
{
  "data": {
    "url": null,
    "deleted": true
  }
}
```

Errors: the common errors only.

### POST /webhooks/rotate-secret

**Rotate the signing secret.** operationId `rotateWebhookSecret`. Scope: `webhooks:manage`. X-PE-Actor-Email: optional.

Make a new signing secret. PE signs deliveries with the new secret from now on. Update your receiver at once.

Response: HTTP 200, `data` is `WebhookWithSecret`.

```json
{
  "data": {
    "url": "https://crm.installer.example/pe/webhooks",
    "events": [
      "project.ic_approved",
      "project.pc_approved",
      "project.action_created"
    ],
    "secretVersion": 2,
    "signingSecret": "whsec_exampleNewSecretValueShownOnce"
  }
}
```

Errors (besides the common errors): [`WEBHOOK_NOT_CONFIGURED`](#error-WEBHOOK_NOT_CONFIGURED).

### POST /webhooks/test

**Send a test event.** operationId `testWebhook`. Scope: `webhooks:manage`. X-PE-Actor-Email: optional.

Send a signed `webhook.test` event to your URL now and return the result. The call waits up to 5 seconds for your receiver.

Response: HTTP 200, `data` is `WebhookTestResult`.

```json
{
  "data": {
    "eventId": "evt_Tz8Kp3Lm6Qw9Rx2Vb5Nc7Df1",
    "type": "webhook.test",
    "delivered": true,
    "statusCode": 200,
    "durationMs": 184
  }
}
```

Errors (besides the common errors): [`WEBHOOK_NOT_CONFIGURED`](#error-WEBHOOK_NOT_CONFIGURED).

## Endpoint reference: Sandbox

### POST /sandbox/projects/{projectId}/simulate

**Simulate a PE event.** operationId `simulateProjectEvent`. Scope: `projects:read`. X-PE-Actor-Email: optional. Test keys only.

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.

Request body (`SimulateRequest`):

| Field | Type | Required | Notes |
|---|---|---|---|
| `event` | `document_approved`, `document_rejected`, `action_raised`, `photos_approved`, `ic_approved`, `pc_approved`, `project_cancelled`, `contract_viewed`, `contract_signed`, `contract_declined`, `contract_voided`, `contract_expired` | yes | A simulated PE event on a Test project. |
| `documentType` | string | no | Document_approved, document_rejected; optional on action_raised. 1 to 100 characters. |
| `reason` | string | no | Document_rejected: the reviewer comment. Contract_declined and contract_voided (optional): the reason. 1 to 1000 characters. |
| `title` | string | no | Action_raised: the Action title. 1 to 200 characters. |

```json
{
  "event": "document_rejected",
  "documentType": "utilityBill",
  "reason": "The bill is older than 12 months. Upload a recent bill."
}
```

Response: HTTP 200, `data` is `SimulateResult`.

```json
{
  "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"
  }
}
```

Errors (besides the common errors): [`RESOURCE_NOT_FOUND`](#error-RESOURCE_NOT_FOUND), [`SANDBOX_DOCUMENT_TYPE_UNKNOWN`](#error-SANDBOX_DOCUMENT_TYPE_UNKNOWN), [`SANDBOX_TRANSITION_INVALID`](#error-SANDBOX_TRANSITION_INVALID).

### GET /sandbox/scenarios

**List the Test upload scenarios.** operationId `listSandboxScenarios`. Scope: none. X-PE-Actor-Email: optional. Test keys only.

List the contract upload scenarios of the Test environment, with the result of each. Test keys only.

Response: HTTP 200, `data` is `ScenarioList`.

```json
{
  "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
      }
    ]
  }
}
```

Errors: the common errors only.

## Webhook events

See Webhooks for the headers, the retries and the signature check. `project.ic_approved` and `project.pc_approved` carry `ApprovalEvent`. `project.action_created` carries `ActionCreatedEvent`: `data` has `projectId`, `externalId` and `action`, and `action` is an `Action`. `webhook.test` carries `TestEvent` with an empty `data`.

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

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

#### INVALID_JSON

HTTP 400. Retry the same request: no.

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

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.

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

#### VALIDATION_FAILED

HTTP 400. Retry the same request: no.

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

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

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

#### UNKNOWN_FIELD

HTTP 400. Retry the same request: no.

> The request has {count} field(s) this endpoint does not accept: {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.

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

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

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

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

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

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

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

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

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

#### WEBHOOK_URL_INVALID

HTTP 400. Retry the same request: no.

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

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

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

#### WEBHOOK_URL_NOT_HTTPS

HTTP 400. Retry the same request: no.

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

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

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

#### SANDBOX_SCENARIO_INVALID

HTTP 400. Retry the same request: no.

> The sandboxScenario {received} is not one of: {allowed}. Send one of the 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

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

#### AUTH_HEADER_MISSING

HTTP 401. Retry the same request: no.

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

When: The request has no Authorization header.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#### ENVIRONMENT_NOT_ENABLED

HTTP 403. Retry the same request: no.

> The {environment} environment is not enabled for your company. Use a 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.

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

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

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

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

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

#### SCOPE_NOT_GRANTED

HTTP 403. Retry the same request: no.

> This endpoint needs the scope {scope}, and your 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.

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

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

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

#### STATE_NOT_ACTIVE_FOR_INSTALLER

HTTP 403. Retry the same request: no.

> The installer is not active in {stateCode}. Use a state from GET /v2/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.

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

#### PRODUCT_NOT_ENABLED

HTTP 403. Retry the same request: no.

> The product {productType} is not enabled for this installer. 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.

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

#### SUNGAGE_NOT_ENROLLED

HTTP 403. Retry the same request: no.

> This installer is not enrolled in the Participate Energy and Sungage program, or its Sungage account is not set up in Raceway. 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.

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

#### SUNGAGE_USER_NOT_REGISTERED

HTTP 403. Retry the same request: no.

> Sungage did not accept the actor email as a user of this installer's Sungage account. Send the email of a user registered with Sungage 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.

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

#### INSTALLER_ON_HOLD

HTTP 403. Retry the same request: no.

> This installer cannot create new projects right now because its account is on hold. Contact Participate Energy at raceway.support@participate.energy.

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

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

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

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

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

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

#### RESOURCE_NOT_FOUND

HTTP 404. Retry the same request: no.

> No {resource} with this id is available to your 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.

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

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

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

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

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

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

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

#### METHOD_NOT_ALLOWED

HTTP 405. Retry the same request: no.

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

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

### HTTP 409: conflict

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

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

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

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

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

#### UPLOAD_ALREADY_SUBMITTED

HTTP 409. Retry the same request: no.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#### SANDBOX_TRANSITION_INVALID

HTTP 409. Retry the same request: no.

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

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.

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

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

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

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

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

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

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

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

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

#### UPLOAD_URL_EXPIRED

HTTP 410. Retry the same request: no.

> The upload URL for upload {uploadId} expired before a file arrived. Create a new upload with POST /v2/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.

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

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

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

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

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

#### BODY_TOO_LARGE

HTTP 413. Retry the same request: no.

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

When: The JSON body is larger than 1 MiB.

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

#### UPLOAD_FILE_TOO_LARGE

HTTP 413. Retry the same request: no.

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

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

### HTTP 415: media type

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

#### UNSUPPORTED_MEDIA_TYPE

HTTP 415. Retry the same request: no.

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

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

### HTTP 422: the request breaks a rule

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

#### ADDRESS_NOT_FOUND

HTTP 422. Retry the same request: no.

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

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.

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

#### ADDRESS_OUTSIDE_US

HTTP 422. Retry the same request: no.

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

When: The address is outside the United States.

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

#### ADDRESS_PO_BOX

HTTP 422. Retry the same request: no.

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

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.

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

#### STATE_NOT_SUPPORTED

HTTP 422. Retry the same request: no.

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

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

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

#### STATE_MISMATCH

HTTP 422. Retry the same request: no.

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

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

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

#### UTILITY_NOT_FOUND

HTTP 422. Retry the same request: no.

> The utility is not on the list for {stateCode}. Use a name from GET /v2/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.

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

#### OWNERSHIP_NOT_ELIGIBLE

HTTP 422. Retry the same request: no.

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

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

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

#### EXISTING_SOLAR_NOT_ELIGIBLE

HTTP 422. Retry the same request: no.

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

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.

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

#### EQUIPMENT_NOT_ON_AVL

HTTP 422. Retry the same request: no.

> The equipment {sku} is not on the Participate Energy approved vendor list. Use a SKU from GET /v2/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.

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

#### EQUIPMENT_AMBIGUOUS

HTTP 422. Retry the same request: no.

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

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

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

#### EQUIPMENT_CATEGORY_MISMATCH

HTTP 422. Retry the same request: no.

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

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.

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

#### EQUIPMENT_QUANTITY_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

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

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.

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

#### SALES_TAX_UNRESOLVED

HTTP 422. Retry the same request: no.

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

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

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

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

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

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

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

#### EPC_PER_WATT_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

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

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.

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

#### CONTRACT_DATE_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

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

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.

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

#### CONTRACT_DATE_BEFORE_RETITC_CUTOFF

HTTP 422. Retry the same request: no.

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

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.

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

#### INCENTIVE_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

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

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

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

#### ROOFING_COST_NOT_APPLICABLE

HTTP 422. Retry the same request: no.

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

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

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

#### AMOUNT_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

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

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.

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

#### SYSTEM_SIZE_LOOKS_LIKE_WATTS

HTTP 422. Retry the same request: no.

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

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.

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

#### SYSTEM_SIZE_OUT_OF_RANGE

HTTP 422. Retry the same request: no.

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

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

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

#### ROOFING_COST_INVALID

HTTP 422. Retry the same request: no.

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

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

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

#### SAFE_HARBOR_UNITS_INVALID

HTTP 422. Retry the same request: no.

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

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

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

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

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

#### SUNGAGE_PRODUCT_UNAVAILABLE

HTTP 422. Retry the same request: no.

> The Sungage product, term or rate is not available for this installer and project. Use a combination from GET /v2/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`).

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

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

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

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

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

#### UPLOAD_FILE_MISSING

HTTP 422. Retry the same request: no.

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

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

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

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

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

#### UPLOAD_NOT_PDF

HTTP 422. Retry the same request: no.

> The file for upload {uploadId} is not a PDF. 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`).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#### WEBHOOK_URL_PRIVATE_ADDRESS

HTTP 422. Retry the same request: no.

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

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

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

#### WEBHOOK_NOT_CONFIGURED

HTTP 422. Retry the same request: no.

> No webhook URL is set for the {environment} environment. Set one with PUT /v2/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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#### RATE_LIMITED

HTTP 429. Retry the same request: yes.

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

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

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

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

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

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

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

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

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

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

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

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

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

#### UPSTREAM_TIMEOUT

HTTP 504. Retry the same request: yes.

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

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

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

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

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

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

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

#### EC_LOOKUP_UNAVAILABLE

HTTP 503. Retry the same request: yes.

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

When: The Energy Community data service did not answer.

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

#### TAX_RATE_UNAVAILABLE

HTTP 503. Retry the same request: yes.

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

When: The sales tax rate service did not answer.

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

#### ADDRESS_LOOKUP_UNAVAILABLE

HTTP 503. Retry the same request: yes.

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

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

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

#### SUNGAGE_UNAVAILABLE

HTTP 503. Retry the same request: yes.

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

When: Sungage did not answer.

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

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