DOCSEARCHbyAlgolia
Submit Docs

OpenSolar API Documentation

website·Indexed 34 days ago

https://developers-staging.opensolar.com

Developer documentation for the OpenSolar API, covering endpoints for managing projects, organizations, contacts, and proposal data. Includes detailed guides on authentication using bearer tokens, webhook configurations for project and quote events, and managing connected organizations and shared entities.

Tokens
25.1K
Snippets
111
Records
163
Agent score
49%

What's inside OpenSolar

  1. Understand the Contact webhook payload structure

    A Contact webhook payload provides details about contacts associated with a project. The payload includes metadata such as the event type (e.g., UPDATE), a unique identifier, and a fields object containing the contact's personal details, organization reference, and associated projects.
    {
  "timestamp": "1605832666",
  "model": "Contact",
  "model_id": 5,
  "identifier": "6ab6a60d-1a4d-4374-88af-92f7c02e3223",
  "event": "UPDATE",
  "event_id": 1,
  "fields": {
    "display": "george costanza",
    "email": "george@vanderlayindustries.com",
    "family_name": "costanza",
    "first_name": "george",
    "id": 5,
    "org": "/api/orgs/14/",
    "phone": "99991234",
    "projects": ["/api/orgs/14/projects/10/"],
    "url": "/api/orgs/14/contacts/5/",
    "user": "/auth/users/6/"
  }
}

  2. Integrate OpenSolar with third-party platforms via partners

    OpenSolar provides a network of trusted third-party integration partners to connect the platform with tools like Salesforce, Hubspot, and Zapier without requiring in-house development. Key partners include:

    • Snapfrozen: Provides software integrations to automate and streamline solar business workflows.
    • Pale Blue Dawn: An official integration partner focused on connecting OpenSolar to a full tech stack to reduce manual data entry and installation times.

  3. Manage private files for an organization

    The Private Files API provides endpoints to manage private files scoped to an organization. Authenticated users must be a 'Pro' for the organization to use these endpoints. Throttling is limited to 1000 requests per day per organization for both read and write operations.

    Endpoints

    • GET /api/orgs/:org_id/private_files/ : List private files
    • GET /api/orgs/:org_id/private_files/:file_id/ : Retrieve a private file
    • POST /api/orgs/:org_id/private_files/ : Create a private file
    • PATCH /api/orgs/:org_id/private_files/:file_id/ : Update a private file
    • DELETE /api/orgs/:org_id/private_files/:file_id/ : Delete a private file

  4. Understand the OpenSolar Data Schema Hierarchy

    The OpenSolar data model is centered around Organizations (Orgs), which contain both customer-specific data and global configuration settings.

    Customer Data Hierarchy:

    • Orgs contain Projects and Contacts.
    • Projects act as the primary container for site-specific data, including:
      • Systems: The technical solar designs for the project.
      • Assigned Personnel: Links to Contacts/Roles for Team Members, Site Inspectors, and Installers.
      • Tariffs: Links to the Current and Proposed Utility Tariffs.
      • Events: Project-related milestones or appointments.
      • Private Files: Documents specific to that project.

    Organization Configuration:

    • Orgs maintain global settings including API Keys, Pricing Schemes, Payment Options, and Costings.
    • Component Activations: Defines which Modules, Inverters, and Batteries from the Component Database (or custom entries) are active for the Org.
    • Operational Settings: Includes Setbacks, Design Settings, Incentives, Document Templates, and Lead Capture Forms.

    Global Entities:

    • Certain entities exist independently of specific Orgs, such as Event Types and Roof Types.

  5. Understand OpenSolar webhook payload structure

    OpenSolar triggers webhooks for five specific models: Project, Contact, Event, Quote, and QuoteActivityLog. The payload contains metadata about the event and the modified data. The fields object is only included for CREATE and UPDATE events.
    {
  "timestamp": "1605831713",
  "model": "Project",
  "model_id": 1,
  "identifier": "6ab6a60d-1a4d-4374-88af-92f7c02e3223",
  "event": "UPDATE",
  "event_id": 1,
  "fields": {
    ... 
  }
}

  6. Understand OpenSolar API throttling types

    OpenSolar enforces two types of throttling to maintain performance and prevent misuse. Note that all endpoints have a throttle quota applied, even if not explicitly listed in the documentation.

    • Throttling per User: Limits the number of requests a specific user can make to an endpoint.
    • Throttling per Org: Limits the total number of requests all users within a specific organization can make to an endpoint.

  7. Quote webhook payload field reference

    The Quote webhook payload provides comprehensive details about a supplier quote. Key fields include:

    • Identification & Status: id (integer), status (string, e.g., under_review, awaiting_order, ordered), and project_id (integer | null).
    • Location: address, zip, state, locality, county (null able), and country (ISO 3166-1 alpha-2).
    • Dates: created_date (datetime), modified_date (datetime), quote_valid_until (date | null), and estimated_delivery_date (date | null).
    • Entities: org_name (owner) and supplier_name (supplier).
    • Contacts: pro_contact (object containing display, email, phone) and account_manager_data (array of objects containing display, email, phone).
    • Financials & Items: data (object containing line items keyed by index), cost_summary (object with subtotal, discount, shipping, tax, total), and custom_data (object | null).
    • Attachments: files (array of objects with file_name and file_url).

  8. Understand the Project Webhook payload structure

    When receiving a project webhook, the payload contains metadata about the event and a fields object containing the full state of the Project model.

    Key top-level fields include:

    • timestamp: The time the event occurred.
    • model: The entity type (e.g., "Project").
    • model_id: The unique ID of the project.
    • identifier: A UUID for the project.
    • event: The type of change (e.g., "UPDATE").
    • fields: A detailed object containing project-specific data such as business_name, configuration, costing, and private_files_data.

    Important Note on Files: The file_contents URL provided within the private_files_data array is time-delimited and expires after 1 hour.

    {
  "timestamp": "1605832669",
  "model": "Project",
  "model_id": 12,
  "identifier": "6ab6a60d-1a4d-4374-88af-92f7c02e3223",
  "event": "UPDATE",
  "event_id": 1,
  "fields": {
    "business_name": "Vandelay Industries",
    "configuration": {
      "discount_rate": 6.75,
      "utility_inflation_annual": 3
      // ... other config settings
    },
    "private_files_data": [
      {
        "title": "sample.pdf",
        "file_contents": "https://localhost:8000/media/private/sample.pdf?Expires=1639011238"
      }
    ]
    // ... other project fields
  }
}

  10. Understand the OpenSolar Webhooks Event payload structure

    When a webhook event is triggered for a project in OpenSolar, the payload contains metadata about the event (such as the model, event type, and timestamp) and a fields object containing the specific details of the affected entity. The event field indicates the action taken (e.g., UPDATE), and the fields object provides a comprehensive set of attributes including project identifiers, dates, and user information.
    {
  "timestamp": "1605832669",
  "model": "Event",
  "model_id": 5,
  "identifier": "6ab6a60d-1a4d-4374-88af-92f7c02e3223",
  "event": "UPDATE",
  "event_id": 1,
  "fields": {
    "action": "/api/orgs/27/actions/1/",
    "archive_for": null,
    "completion_date": "2020-01-01T12:00:00.000000Z",
    "contact": "/api/orgs/15/contacts/6/",
    "created_date": "2020-01-02T12:00:00.000000Z",
    "duration": 0,
    "end": null,
    "event_type_id": 29,
    "id": 5,
    "is_archived": false,
    "is_complete": true,
    "location_override": "",
    "modified_date": "2020-01-01T12:00:00.000000Z",
    "notes": null,
    "org": "/api/orgs/15/",
    "project": "/api/orgs/15/projects/11/",
    "project_name": "Vandelay Industries",
    "repeat": 0,
    "start": null,
    "task_status": 0,
    "team_members": [],
    "title": "Design Systems",
    "url": "/api/orgs/15/events/5/",
    "user": "/auth/users/7/",
    "who": {
      "display": "george costanza",
      "email": "george@vanderlayindustries.com",
      "portrait_image_public_url": null
    }
  }
}

  11. Retrieve details for a specific user role

    Use the GET /api/orgs/:org_id/roles/:id/ endpoint to get detailed information about a specific user role. This endpoint supports the following query parameters for filtering and pagination: fieldset (for listing), range, page, limit, and ordering (supported fields: id, is_admin).

  12. Understand the Project object structure in Proposal Data API

    The Project object within the OpenSolar Proposal Data API provides comprehensive details about a specific project, including its location, customer contacts, system configurations, and utility data. It serves as a container for the proposal_data object used to generate online proposals.