Scanifly API Overview

The Scanifly API enables you to integrate your other applications seamlessly with the Scanifly Platform. You will be able to leverage our APIs to create workflows, minimize time spent on duplicate data entry, and mitigate the risk of potential data loss. We have built the Scanifly API with security in mind so you do not have to worry about anyone having access to your sensitive company data but you.

This document will provide some suggestions on how to integrate Scanifly into your existing proposal and / or design processes. It is meant to supplement the API docs that provide the call and field level structure.

General Guidance for Using Scanifly APIs

• Only populated fields will be sent in responses. If an optional value is not populated in the database, that field may not be included in the response.
• URLs included in responses are valid for 24 hours. Attempting to access those URLs past the expiration will result in an authorization error.

Getting Started

Generate an API Key

You will need to generate an API key on your company's admin account.

1. On an Admin account, navigate to the Settings

2. Select Access Tokens

3. Click the New Access Token button.

4. Select your CRM, or if your tool is not listed "Other", from the drop down list.

5. Store this key with your API calls or in your CRM tool.

Syncing Project Data

Scanifly API's supports creating and updating projects as part of your workflow.

Create Project

Making the Create project call

Reference Link

There are only a two fields that are required when creating the project through the API, the others are optional.

• name
• address

Currently, we do not support translating geolocation to an address when creating a project from the API. This will be supported in the future.

If you have consumption data that you would like to factor into modeling, you can send this data with the Create project or Update project calls. You are required to send 12 values in the kwh array, first value in the list represents data for January.

Validation

• Invalid addresses will receive a 400 error
• If sending consumption data, 12 values representing each months consumption (starting with January)

Create Project Response

Scanifly will send the Scanifly Project ID back in the response. This value is required in most of the following calls that you will likely be making. Store the Scanifly project ID with your internal ID.

Adding Projects to Folders

Scanifly supports organizing projects into folders. Some companies organize projects by region or team member, and create folders accordingly, configuring users' access to these folders in the portal. Some companies just have a single folder for all projects. Once a project is created, you may want to place it in a particular folder if you are organizing projects into particular folders.

Folders can be created in the Portal or from an API call. We will be deploying a call to retrieve all folders by company ID soon.

Create a folder Call

Reference Link

You will be required to pass the folder name and the hex for the color that you'd like to associate with the folder in the portal.

Create a folder Response

The response will return the folder's ID. This should be stored in your system to use in subsequent calls.

Add Project to Folder Call

Make a POST request: https://api.portal.scanifly.com/api/v1/folders/{id}/projects/{projectId}

Add Project to Folder Response

Update Projects

There are scenarios where you may want to update. If you capture the customer's consumption data or would like to add additional client contact information, you can make those requests in the Update projects call.

Make a PATCH call: https://api.portal.scanifly.com/api/v1/projects/{projectId}

Sample Update Projects Call

In this call, the project name and consumption data are being updated on the project.

Sample Update Projects Response

Project Statuses

Project status is returned in the response to the Create and Update project calls. These statuses can be used as triggers to manage workflow in your CRM.

Designs

Once a project has been created, you can create a design on that project. Scanifly offers Design Services, that will be addressed in Service Requests.

Create design on project id

Reference Link

Scanifly supports two types of designs:

Remote: Designs based on satellite imagery

On-Site: Designs based on photogrammetry generated by drone images

When creating a new design, you have the option to set which type of design you would like to create. If you do not pass a value, the "remote" value will default to "true', meaning, the design will be a remote design.

• remote: true (Remote design based on satellite imagery)
• remote: false (On-Site design based on drone imagery)

Sample Create design on project id call

Sample Create design on project id response

When you receive the Create design response, you should store the id value in your system so that you can make subsequent calls to retrieve design specific data and media files.

The Create design on project id response will also include the 'designUrl'. This can be stored in your system so that your team can click a the link from your CRM and open the design in Scanifly, eliminating clicks to navigate to the project and design.

Syncing Designs (Get designs by project id and Get designs by design id)

You have two calls available to retrieve design data.

"Get designs by project id" will return all designs associated with a project. This is useful if rely on multiple design versions in your workflow.

"Get designs by design id" narrows the response to the one design that you are interested in syncing. (Coming soon.)

There are a few things to keep in mind when examining and parsing the data:

• The shadeReport Url will only be populated if a user has done the following in Scanifly:

  • Generated the shade report
  • Clicked the Export to API button
  
  

• The shareLinkUrl will only be populated if a user has filled out and clicked the Share button on the 'Share' information tab on the design.

<

Data in _Get designs by project id _response

There is a significant amount of data passed in the Get design calls. For the best experience, please go to the API doc and submit a test request to see the full response. This is a brief overview (does not include all fields in response) of the data that you are able to extract from the response.

Checklists

Checklists are used to record and report on site specific data needed to prepare designs, submit financial documents, confirm installations and many other tasks. The pdf version of the checklist report and associated media files can be synced with your system by following the below steps.

Checklists have statuses. You can monitor status and the updatedAt values on a checklist to trigger workflows, such as downloading media files.

Step 1: Make the Get Checklist by project id call to retrieve the list of checklists associated with the project.

Reference Link

GET https://api.portal.scanifly.com/api/v1/checklist/{projectId}

Sample Get Checklist by project id response

Some tips to consider:

• To minimize making the same call, you may want to consider storing the highlighted id below. This will be used in subsequent steps and you may want to make additional calls in the future, depending on your workflow.
• The response includes a link to the pdf report of checklist (if the checklist is complete). This link is valid for 24 hours. If the link has expired, you will receive an authentication error.

Step 2: Make the Get checklist by id call

Reference Link

GET https://api.portal.scanifly.com/api/v1/checklist/{projectId}/{checklistId}

You will pass the id value from Step 1 in the URL.

There are fields in the response that you may be interested in parsing out:

Sample Get checklist by id response

Step 3: Make the _Get Media by category ID _call

Reference Link

GET https://api.portal.scanifly.com/api/v1/media/{projectId}/{categoryId}

The categoryId is the mediaCategoryId from step 2.

The response will include links to media files. I believe these links are valid for 24 hours. If you make the call outside of the 24 hour period you'll get an authentication error.

There are fields in the response you may be interested in parsing out or downloading:

Sample Get Media by Category id response