Tutorials

Request a roof model built

This tutorial shows how to programmatically create a request for a 3D roof model from Aurora’s Expert Modeling Service.

How It Works


You create an Expert Modeling Service request for an Aurora project. Upon receipt of the request, Aurora designers build a 3D roof model. On your accepting the model, a new design with the 3D roof model is added to your project.

Getting Started


To complete this tutorial, you will need:

  • your Aurora tenant to be on the Custom or Business plan,
  • your Aurora tenant to use the current API version,
  • your Aurora bearer token,
  • your Aurora tenant_id,
  • URL to deliver Aurora webhooks to.

You or any Administrator for your Aurora tenant can retrieve the token and tenant id from the API Settings page.

Step 1. Subscribe to a design request completion webhook event.


Subscribe to the design_request_completed webhook event, pointing webhooks to your application that will process them.

//POST https://api-sandbox.aurorasolar.com/tenants/{tenant_id}/webhooks

  {
  "webhook": {
    "description": "Design Request Completed",
    "event": "design_request_completed",
    "url_template": "https://www.yourcompany.com/aurora_design_request_completed_webhooks?design_request_id=<DESIGN_REQUEST_ID_IN_AURORA>&status=<STATUS>",
    "enabled": true
  }
}

Step 2. Create a project.


Create a project using an address that will be instantly filled by the mock Expert Modeling Service.

//POST https://api-sandbox.aurorasolar.com/tenants/{tenant_id}/projects

{
     "project": {
          "address": "901 Mears Ct, Stanford, CA 94305, USA"
     }
}

//HTTP 200 response

{
    "project": {
        "id": "a09d77f4-c98c-4681-b172-07ba6cae39b3",
        "external_provider_id": null,
        "name": null,
        "customer_salutation": null,
        "customer_first_name": null,
        "customer_last_name": null,
        "customer_address": null,
        "customer_email": null,
        "customer_phone": null,
        "address": "901 Mears Ct, Stanford, CA 94305, USA",
        "latitude": 37.4162953,
        "longitude": -122.1570644,
        "project_type": "residential",
        "owner_id": null,
        "status": null
    }
}

Step 3. Make an Expert Modeling Service request.


Request a roof model to be created for the project_id returned by the request above.

//POST https://api-sandbox.aurorasolar.com/tenants/{tenant_id}/design_requests

{
     "design_request": {
          "project_id": "a09d77f4-c98c-4681-b172-07ba6cae39b3",
          "sla": 180,
          "auto_accept": true
     }
}

Step 4. Look up design id for the newly created design.


On the webhook receipt, look up the design_id for the newly created design.

//Webhook query string payload
?design_request_id_in_aurora=1a52d42f-7b03-40f4-94be-e393ed8c5386&status=designer_completed

//GET https://api-sandbox.aurorasolar.com/tenants/{tenant_id}/design_requests/{design_request_id}
{
    "design_request": {
        "id": "1a52d42f-7b03-40f4-94be-e393ed8c5386",
        "project_id": "a09d77f4-c98c-4681-b172-07ba6cae39b3",
        "status": "accepted",
        "design_id": "d71204cf-a570-416c-9693-0fd4cdce9c05",
        "address": "901 Mears Ct, Stanford, CA 94305, USA",
        "latitude": 37.4162953,
        "longitude": -122.1570644,
        "submitted_at": "2022-04-21T05:10:02.485Z",
        "completed_at": "2022-04-21T05:10:02.515Z",
        "reviewed_at": "2022-04-21T05:10:02.808Z",
        "image_src": "Google",
        "lidar_src": "Aurora Lidar",
        "sla": 180,
        "designer_rejection_reason": null,
        "auto_accept": true,
        "auto_accepted": true
    }
}

Considerations


  • Consider using a webhook test site like https://webhook.site to verify that your webhook subscription is live.