The Service Request calls provides a way for you to communicate with the Scanifly Design Services team. You are able to place an order for a new design as well as check the status on existing orders.
POST https://api.portal.scanifly.com/api/v1/serviceRequests?access_token={access_token}
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| projectId | String | Yes | Project ID that the service request is associated with |
| status | String | Yes | Initial status of the service request, "ordered" |
| tierLevel | String | Yes | Requested service tier (e.g., "maxFill") |
| form | Object | Yes | Object containing design parameters and requirements. See below |
| upgrade | Boolean | Yes | Indicates if this is an upgrade request. Set to true or false |
| isExpedited | Boolean | Yes | Indicates if expedited processing is required. Set to true or false. |
form Object Details
Field | Type | Required | Description |
|---|---|---|---|
sizedForCategory | String | Yes | Specifies the criteria for sizing the system (e.g., "consumption", "production", “systemSize”). |
sizedForValue | String | Yes | The numerical value associated with sizedForCategory (e.g., 105 could mean 105% offset or 105 kWh depending on the category). |
fireSetbacks | Object | Yes | Defines setback requirements for fire safety. Contains keys like ridge, eave, rake, valley, hip. Values would be numbers or "undefined" for defaults.\ ridge = NYC: 3’ LI/WcCO: 18” Eave = NYC/LI/WcCO: 8” Rake = NYC: 8” LI/WcCo: 22” Valley = NYC/LI/WcCO: 6” Hip = NYC: 8” LI/WcCO: 22” |
obstructionSetbacks | Object | Yes | Defines setback requirements around obstructions. Contains keys like vents, exhaust, skylights, parapet, general. Values might be numbers or "undefined".\ vents, exhaust, skylights,general = 5” Parapet = 1’ |
projectAddress | String | Yes | The full street address for the project location. |
homeownerName | String | Yes | The name of the homeowner associated with the project. |
designOneModule | String | Yes | Specifies the primary solar module type to be used in the design (e.g., "SunPower X21 Black").\ Based on the picklist selection |
moduleOrientation | String | Yes | The default orientation for modules (e.g., "portrait", "landscape").\ Default = portrait |
mixedOrientation | String | Yes | Whether modules can have mixed orientations ("yes" or "no").\ Default = “yes” |
moduleSpacingLong | String | Yes | Required spacing along the longer edge of the module (Units assumed, e.g., inches. The value is provided as a string). Default 1 inch |
moduleSpacingShort | String | Yes | Required spacing along the shorter edge of the module (Units assumed, e.g., inches. The value is provided as a string). |
azimuthRangeStart | String | Yes | The minimum acceptable roof surface azimuth (degrees, e.g., "90" for East. The value is provided as a string).\ Azimuth Start = 0 |
azimuthRangeEnd | String | Yes | The maximum acceptable roof surface azimuth (degrees, e.g., "270" for West. The value is provided as a string).\ Azimuth End = 360 |
newBuildPlansRequired | Boolean | Yes | Indicates if plans for a new construction are required. |
isCommercialZone | Boolean | Yes | Indicates if the project location is in a commercial zone. |
negativeTolerance | Number | Null | No |
positiveTolerance | Number | Null | No |
Example Request Body
Response
Response will be returned in the form of a JSON object containing the details of the newly created Service Request.
| Field | Type | Description |
|---|---|---|
| id | String | The unique identifier for the newly created service request. |
| companyName | String | Name of the company associated with the request. |
| projectDesign | Object | Contains the id (String) of the associated project design artifact. |
| userInfo | Object | Information about the user who created the request (id, firstName, lastName, email). |
| status | String | The current status of the service request (e.g., "ordered"). |
| tierLevel | String | The tier level assigned to the request (e.g., "maxFill"). |
| addOns | Array | List of any add-ons associated with the request (potentially objects). |
| form | Object | An echo of the form object submitted in the request. |
| designServiceProviderId | String | Identifier for the design service provider assigned to this request. |
| designServiceProviderName | String | Name of the assigned design service provider. |
| isExpedited | Boolean | Indicates if the request is marked as expedited. |
| isAutomated | Boolean | Indicates if the request processing was (or will be) automated. |
| createdAt | String | ISO 8601 timestamp indicating when the request was created. |
| updatedAt | String | ISO 8601 timestamp indicating when the request was last updated. |
| project | Object | Details of the associated project (id, name, status, mode) |
| company | Object | Contains the id (String) of the associated company. |
| modelRevisionCount | String | Revision count for the associated model (starts at "0") |
Example Success Response Body
Error Responses
| Status Code | Reason |
|---|---|
| 400 Bad Request | The request body is malformed, missing required fields, or contains invalid data types. The response body might contain details about the specific validation errors. |
| 401 Unauthorized | Authentication failed. The Authorization header is missing, invalid, or expired. |
| 404 Not Found | The specified projectId does not exist. |
| 500 Internal Server Error | An unexpected error occurred on the server side while processing the request. |