Core Concepts
API v1 is being deprecated. Use v2 for new integrations. For existing integrations, see the migration guide and API Reference v1.
These entities underpin the API Reference v2 and Webhooks.
How the entities relate
Solid arrows show ownership; dotted arrows show user relationships.
The two main entities:
- An Organization is the top-level tenant. Users, roles, and billing live here.
- A Project is the central operational record: design, pricing, financing, and contracts all hang off it. A project belongs to an Installer and is assigned to a Team.
Organization
A company-level tenant containing members, installer profiles, roles, and settings. Users, roles, and billing belong to the organization; projects and operational settings belong to installers. All API access is scoped to your organization.
User
A person with a name, email, and phone, belonging to one or more organizations. Users can join teams and hold multiple roles. Their permissions determine access to installers within each organization.
Role
An organization-specific set of permissions with a name and description.
The default Organization Admin role grants full access (*). A user receives
the union of permissions from all their roles.
Permission
Permissions use scope:action to control what users can do:
| Permission | Grants |
|---|---|
project:create | Create new projects |
project:view_all | View all projects in the organization |
installer:edit_details | Edit installer settings |
team:manage_members | Manage team membership |
Permissions support wildcards: * grants everything, and scope:* grants all actions within a scope (e.g. project:*).
Installer
An installation-company profile with branding (logo, color, website), location, contacts, settings, and teams. An organization can have multiple installers for brands or regions. The installer sets a project's branding and configuration.
Team
A group of users within an installer. Projects are assigned to teams; membership controls project visibility and access.
Project
An installation opportunity linking the homeowner, property, design, pricing, financing, and contract status. Projects are central to the REST API and project webhooks.
Homeowner
The property owner, with name, contact details, and property address. Each project has one homeowner; a homeowner can have multiple projects. These details are required at creation and reused in proposals, contracts, and financing applications.
Working with API v2
A v2 detail response wraps the resource in data. Lists
usually include data and page.nextCursor; follow the individual operation's
schema for exceptions.
Cursor pagination
For a v2 project list, send limit and, on subsequent requests, the opaque
cursor returned as page.nextCursor. Keep the same filters and sort order.
Stop when nextCursor is null; do not decode or construct cursors yourself.
Project creation and readiness
V2 project creation returns 201 with data.id as soon as the project is saved.
Utility setup and automatic design continue in the background. Read the project
and its /design endpoint to follow progress; autoDesignStatus distinguishes
pending, completed, and failed automatic design. A created project does not mean
its design, utility rates, or savings are ready.
Customers and properties
V2 exposes customers and properties separately. Use the identifiers and resource models in the API Reference v2. A project's customer, equipment, design, pricing, and financing have dedicated operations.
Concurrent updates
Where a v2 operation requires If-Match, read the resource's ETag response
header and send that value, including its quotes, with your write. If the resource
changed, read it again and reconcile your intended update. See
Rate Limits & Idempotency.
Maintaining a v1 integration
- Project lists use
pageandpageSizewithpaginationmetadata, rather than v2 cursor pagination. - Project creation returns the project's
iddirectly, rather thandata.id. - Request and response shapes differ. Compare the operations you use before migrating; changing the URL prefix alone is not enough.

