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:

PermissionGrants
project:createCreate new projects
project:view_allView all projects in the organization
installer:edit_detailsEdit installer settings
team:manage_membersManage 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 page and pageSize with pagination metadata, rather than v2 cursor pagination.
  • Project creation returns the project's id directly, rather than data.id.
  • Request and response shapes differ. Compare the operations you use before migrating; changing the URL prefix alone is not enough.