Skip to main content

Projects

A Project stores all the data for a particular project location, including [system designs], assigned contacts and a team members, utility information, project-specific files, events, etc.

Endpoints​

EndpointDescriptionQuery Parameters
GET /api/orgs/:org_id/projects/List Projectspage, limit, fieldset (list, studio)
GET /api/orgs/:org_id/projects/:id/Get Project
POST /api/orgs/:org_id/projects/Create Project
PATCH /api/orgs/:org_id/projects/:id/Update Project
DELETE /api/orgs/:org_id/projects/:id/Delete Project

Assigned Role​

  • project.assigned_role_data is read-only data for the assigned role, specified in project.assigned_role_id.
  • To replace the role assigned to this project, update project.assigned_role with the URL for the new role.
  • To update the data for this role who has been assigned to the project, use the Update Role endpoint for the resource found at the url in project.assigned_role.

Contacts​

  • project.contacts_data is a read-only data for contacts associated with the project.
  • To create a new project while creating or updating a project, use the project.contacts_new field.
  • To update the data for a contact associated with the project, use the Update Contact endpoint for the resource found at the url in project.contacts.
  • To replace the assigned contacts for a project, call the Update Project endpoint and include new contact urls in project.contacts.

Examples​

Getting a list of Projects​

Request 
curl "https://api.opensolar.com/api/orgs/:org_id/projects/"
--header "Authorization: Bearer <token>"
Response 
[
  {
    "id": 3763174,
    "title": "6 Hopetoun Ave",
    "contacts_data": [
      {
        "id": 1721096,
        "email": "gconstanza@vanderlayindustries.com",
        "phone": "0400000000",
        "url": "https://api.opensolar.com/api/orgs/62854/contacts/1721096/",
        "first_name": "George",
        "family_name": "Costanza",
        "display": "George Costanza",
        "passport_number": "",
        "licence_number": "",
        "custom_contact_info_1": "",
        "custom_contact_info_2": "",
        "user_id": null,
        "org_id": 62854,
        "identifier": "",
        "type": 0
      }
    ],
    "business_name": null,
    "address": "6 Hopetoun Ave",
    "url": "https://api.opensolar.com/api/orgs/62854/projects/3763174/",
    "contacts": [
      "https://api.opensolar.com/api/orgs/62854/contacts/1721096/",
      "https://api.opensolar.com/api/orgs/62854/contacts/2774309/"
    ],
    "priority": 2,
    "stars": [],
    "stage": 0,
    "org_id": 62854,
    "is_lite": false,
    "modified_date": "2024-02-12T01:18:20.475934Z",
    "created_date": "2024-01-31T00:58:18.186310Z",
    "shared_with": [],
    "org_name": "Demo Solar Apparatus Install & Maintenance Demo",
    "customer_proposal_data": null,
    "workflow": {
      "id": 3542964,
      "workflow_id": 10422,
      "active_stage_id": 52144
    },
    "custom_data": null
  }
]

Getting a single Project​

Request 
curl --location 'https://api.opensolar.com/api/orgs/:org_id/projects/:project_id/' \
--header 'Authorization: Bearer <token>'
Response 
{
    "access": 2,
    "events": [
      ...
    ],
    "actions": [
      ...
    ],
    "address": "6 Hopetoun Ave",
    "assigned_role_data": {
      ...
    },
    "assigned_role_email": "g****@l*******.com",
    "assigned_role_id": 101776,
    "assigned_role_name": "George Costanza",
    "assigned_role_phone": "*****",
    "assigned_role": "https://api.opensolar.com/api/orgs/62854/roles/101776/",
    "assigned_role_accreditation": "",
    "assigned_installer_role_data": null,
    "assigned_installer_role": null,
    "assigned_site_inspector_role_data": null,
    "assigned_site_inspector_role": null,
    "assigned_designer_role_data": {
      ...
    },
    "assigned_designer_role_email": "g****@l*******.com",
    "assigned_designer_role_id": 101776,
    "assigned_designer_role_name": "George Costanza",
    "assigned_designer_role_phone": "*****",
    "assigned_designer_role": "https://api.opensolar.com/api/orgs/62854/roles/101776/",
    "assigned_salesperson_role_data": {
      ...
    },
    "assigned_salesperson_role_email": "g****@l*******.com",
    "assigned_salesperson_role_id": 101776,
    "assigned_salesperson_role_name": "George Costanza",
    "assigned_salesperson_role_phone": "*******",
    "assigned_salesperson_role": "https://api.opensolar.com/api/orgs/62854/roles/101776/",
    "available_customer_actions": [
      ...
    ],
    "business_identifier": "",
    "business_name": null,
    "configuration_override": null,
    "configuration": {
      ...
    },
    "costing_override": null,
    "costing": {
      ...
    },
    "contacts_data": [
      ...
    ],
    "contacts": [
      ...
    ],
    "contract_date": null,
    "contract": null,
    "country_iso2": "AU",
    "country_name": "Australia",
    "country": "https://api.opensolar.com/api/countries/14/",
    "county": null,
    "created_date": "2024-01-31T00:58:18.186310Z",
    "design": "...",
    "events_data": [
      ...
    ],
    "greenlancer_project_id": null,
    "id": 3763174,
    "identifier": "192984a9-3475-41a3-b136-8947588ac391",
    "is_residential": true,
    "is_pricing_locked": false,
    "installation_date": null,
    "language": "en",
    "language_override": null,
    "last_calculation_error": null,
    "lat": -33.85868365208357,
    "lead_source": "",
    "locality": "Vaucluse",
    "lon": 151.27518445393818,
    "meter_identifier": "",
    "modified_date": "2024-02-12T01:18:20.475934Z",
    "notes": "",
    "number_of_phases": null,
    "number_of_wires": null,
    "number_of_storeys": null,
    "org_id": 62854,
    "org_name": "Demo Solar Apparatus Install & Maintenance Demo",
    "org": "https://api.opensolar.com/api/orgs/62854/",
    "parcel_identifier": "",
    "payment_option_sold": null,
    "priority": 2,
    "private_files_data": [],
    "private_files": [],
    "proposal_message": "",
    "proposal_content": "",
    "contract_terms": "",
    "premium_imagery_activations": [],
    "project_installed": null,
    "project_sold": null,
    "proposal_template": null,
    "proposal_template_settings": {
      ...
    },
    "roof_type": null,
    "serial_numbers_panels": "",
    "serial_numbers_inverters": "",
    "serial_numbers_batteries": "",
    "share_link": "https://api.opensolar.com/share/3763174/?token=ABS2CYSP7aHt8M9lcbs",
    "simulate_first_year_only": false,
    "site_notes": "",
    "sold_date": null,
    "stage_warning": "The stage field is deprecated, and presently represents the project's workflow milestone. Please refer to https://developers.opensolar.com/ for the migration steps.",
    "stage": 0,
    "stars": [],
    "state": "NSW",
    "systems": [
      ...
    ],
    "system_sold": null,
    "system_installed": null,
    "tags_data": [],
    "tags": [],
    "temperature_max_override": null,
    "temperature_min_max": [
      ...
    ],
    "temperature_min_override": null,
    "testimonials_data": [],
    "testimonials": [],
    "timezone_offset": 11.0,
    "title": "6 Hopetoun Ave",
    "transactions_data": [],
    "url": "https://api.opensolar.com/api/orgs/62854/projects/3763174/",
    "usage_annual_or_guess": 7300,
    "usage": "...",
    "utility_tariff_current_guess": {
      ...
    },
    "utility_tariff_current_custom": "null",
    "utility_tariff_current_data": null,
    "utility_tariff_current": null,
    "utility_tariff_or_guess": {
      ...
    },
    "utility_tariff_proposed_custom": "null",
    "utility_tariff_proposed_data": null,
    "utility_tariff_proposed": null,
    "utility_tariff_proposed_or_guess": {
      ...
    },
    "valid_until_date": "2024-02-23",
    "wind_region": null,
    "has_cellular_coverage": 0,
    "federal_income_tax_rate_percentage": null,
    "state_income_tax_rate_percentage": null,
    "power_factor": null,
    "years_to_simulate": 20,
    "zip": "2030",
    "docusign_contract_envelope_id": null,
    "custom_project_info_1": "",
    "custom_project_info_2": "",
    "custom_project_info_3": "",
    "custom_project_info_4": "",
    "custom_project_info_5": "",
    "allow_email_notifications": true,
    "brighte_role_connection_status": "connection_missing",
    "auto_apply_max_simulate_years": false,
    "contract_template_mode": "payment-option",
    "is_lite": false,
    "custom_data": null,
    "shared_with": [],
    "workflows": [
      ...
    ],
    "customer_proposal_data": {
      ...
    },
    "workflow": {
      ...
    },
    "activated_premium_imagery_wallet_product_ids": []
}

Creating a Project​

Request 
curl "https://api.opensolar.com/api/orgs/:org_id/projects/"
--header "Content-Type: application/json"
--header "Authorization: Bearer <bearer-token>"
--request POST
-d '{
"identifier": "123456",
"is_residential": "1",
"lead_source": "Door Knockers",
"notes": "Has a pool, needs LG panel.",
"lat": "35.12364",
"lon": "128.23216",
"address": "123 Fake st",
"locality": "Fakesville",
"state": "NSW",
"country_iso2": "AU",
"zip": "2020",
"number_of_phases": "1",
"roof_type": "https://api.opensolar.com/api/roof_types/6/",
"assigned_role": "https://api.opensolar.com/api/orgs/1/roles/123/", // assigned_installer_role and assigned_site_inspector_role also available
"contacts_new": [
    {
      "first_name": "George",
      "family_name": "Costanza",
      "email": "gconstanza@vanderlayindustries.com",
      "phone": "0400000000",
      "date_of_birth": "1990-01-01",
      "gender": "2" // 0 = unset, 1 = female, 2 = male
    }
  ]
}'
Response 
{
  "address": "123 Fake st",
  "id": 6624,
  "identifier": "123456",
  "lat": 35.12364,
  "lead_source": "Door Knockers",
  "locality": "Fakesville",
  "lon": 128.23216,
  "notes":"Has a pool, needs LG panel.",
  "number_of_phases": 1,
  "org_id": 1,
  "org": "https://api.opensolar.com/api/orgs/1/",
  "state":"NSW",
  "systems": [
    ...
  ],
  "url": "https://api.opensolar.com/api/orgs/1/projects/6624/",
  "zip":"2020",
  "customer_proposal_data":null,
  "assigned_role_data": {
    "id": 1,
    "email": "bob@company.com.au",
    "is_admin": true,
    "user": "https://api.opensolar.com/auth/users/10/",
    "user_email": "bob@company.com",
    "org": "https://api.opensolar.com/api/orgs/30/",
    "is_hidden": false,
    "url": "https://api.opensolar.com/api/orgs/1/roles/50/",
    "first_name": "Bob",
    "family_name": "Company",
    "job_title": "Important Job",
    "accreditation": "",
    "user_phone": "",
    "display": "Bob S. Company",
    "phone": "94811111",
    "allow_email_notifications": true,
    "portrait_image": null,
    "google_calendar_id": null,
    "has_logged_in": true,
    "schedule_meeting_url": "https://calendly.com/bobby/customer-walk-through",
    "schedule_meeting_label": "Schedule a time to discuss!",
    "api_key_chat": "1233-333-11-9000",
    "user_is_staff": true,
    "org_name": "SunCo"
  },
  "assigned_role_email": "bob@company.com",
  "assigned_role_id": 1,
  "assigned_role_name": "Bob S. Company",
  "assigned_role_phone": "94811111",
  "assigned_role": "https://api.opensolar.com/api/orgs/1/roles/50/",
  "assigned_role_accreditation": "",
  "contacts": [
    "https://api.opensolar.com/api/orgs/1/contacts/60/"
  ],
  "contacts_data": [
    {
      "id": 60,
      "first_name": "George",
      "family_name": "Costanza",
      "email": "gconstanza@vanderlayindustries.com",
      "phone": "0400000000",
      "date_of_birth": "1990-01-01",
      "gender": 2,
      "url": "https://api.opensolar.com/api/orgs/1/contacts/60/"
    }
  ]
}

Updating a Project​

In this example we are updating a Project's Stage

Request 
curl --location --request PATCH 'https://api.opensolar.com/api/orgs/:org_id/projects/:project_id/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "workflow": {
        "active_stage_id": 433194,
        "workflow_id": 84617
    },
    "active_stage_id": 433194
}'
Response 
{
  "id": 3763174,
  "identifier": "192984a9-3475-41a3-b136-8947588ac391",
  "org_id": 62854,
  "org": "https://api.opensolar.com/api/orgs/62854/",
  "simulate_first_year_only": false,
  "url": "https://api.opensolar.com/api/orgs/62854/projects/3763174/",
  "customer_proposal_data": null,
  "workflow": {
    "id": 3631398,
    "workflow_id": 84617,
    "active_stage_id": 433194
  },
  "custom_data": null
}

Updating a Project's Energy Consumption​

Request

curl --location --request PATCH 'https://api.opensolar.com/api/orgs/:org_id/projects/:project_id/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "usage": {
    "usage_data_source": "kwh_annual",
    "values": 7314
  }
}'

Supported Usage Values​

Data Sourceusage_data_sourcevalues
Annual Consumption (kWh)kwh_annualInteger ex. (15000)
Monthly Consumption (kWh)kwh_monthlyList of 12 Integers ex. ([100,101,102,103,104,105,106,107,108,109,110,115])
Bi-Monthly Consumption (kWh)kwh_every_second_monthList of 6 Integers ex. ([100, 101, 102, 103, 104, 105])
Quarterly Consumption (kWh)kwh_quarterlyList of 4 Integers ex. ([100, 101, 102, 103])
Daily Consumption (kWh)kwh_daily_per_monthList of 12 Integers ex. ([100,101,102,103,104,105,106,107,108,109,110,115])
Annual Billbill_annualInteger ex. (60000)
Monthly Billsbill_monthlyList of 12 Integers ex. ([100,101,102,103,104,105,106,107,108,109,110,115])
Bi-Monthly Billsbill_every_second_monthList of 6 Integers ex. ([100, 101, 102, 103, 104, 105])
Quarterly Billsbill_quarterlyList of 4 Integers ex. ([100, 101, 102, 103])
Estimate (Low, Medium, High)estimateString. Can either be Low, Medium, or High
warning

Deprecations​

The existing stage field is deprecated and now represents the project's workflow milestone id. See the table below for your reference.

Stage ID and phaseMilestone ID and phase
0 - Designing0 - Presale
1 - Selling1 - Lock Pricing
2 - Installing2 - Sold
3 - Maintaining3 - Installed
4 - Other4 - Others

The project's current stage can be managed using the workflow.active_stage_id field.