# Quantiv API

Welcome to the Quantiv API documentation! 

The Quantiv API empowers developers with seamless access to powerful data-driven solutions. Our suite of APIs enables you to efficiently interact with key resources, automate processes, and enhance your applications with reliable insights.

Whether you're integrating property intelligence, optimizing lead quality assessments, or leveraging advanced data analytics, Quantiv provides the tools you need to drive smarter decisions and maximize efficiency.

Get started today and unlock the full potential of our APIs!

### 🧐 Overview
  
The Quantiv API is organized around REST principles, utilizing standard HTTP methods, response codes, and authentication. It accepts requests with a JSON body and returns responses in JSON format. The API only supports HTTPS-secured communication. Standard HTTP status codes are used to indicate request outcomes. Error responses include `error`, `statusCode`, and `message` fields for clear debugging.
### 🌐 Endpoint
  The Quantiv API uses a single endpoint for both sandbox and production environments.
   | Environment | Endpoint URL                            |
   |-------------|-----------------------------------------|
   | Sandbox    | [https://public-api.quantiv.io](https://public-api.quantiv.io) |
   | Production | [https://public-api.quantiv.io](https://public-api.quantiv.io) |

### 🔐 Authentication

You will be provided with two API keys. The key with the `sandbox` prefix should be used for requests to the sandbox environment, while the key with the `production` prefix should be used for requests to the production environment.  

The API key must be included in the `token` request header for each API request.

### 📝 Response Status Codes
  
The Quantiv API follows standard HTTP response codes to communicate the outcome of an API request. Generally, codes in the 200 range represent successful requests, codes in the 400 range indicate errors in the request, and codes in the 500 range denote server-side issues.

  | Status Code | Status Message        | Description                                    |
  |-------------|-----------------------|------------------------------------------------|
  | 200         | Success               | The request was successfully processed.        |
  | 400         | Bad Request           | The request was malformed or had invalid syntax. |
  | 401         | Unauthorized          | The provided authentication credentials were invalid. |
  | 404         | Not Found             | The requested resource could not be located.   |
  | 500         | Internal Server Error | An error occurred on the server while processing the request. |

### ⚠️ Business Errors

The Quantiv API returns a status code of **400 Bad Request** for business-related errors. The response will include the details of the error, as outlined in the table below.

  | Case                              | Error        | StatusCode | Message                                                           |
  |-----------------------------------|--------------|------------|-------------------------------------------------------------------|
  | Incorrect Payment Status         | Bad Request  | 400        | Account is paused due to failed payment. Contact Quantiv Admin.   |
  | Inactive API Product Triggered   | Bad Request  | 400        | Product is not activated. Contact Quantiv Admin.                  |
  | Reaching API Usage Limit         | Bad Request  | 400        | API Monthly Limit is reached. Contact Quantiv Admin.              |
  | Reaching $0 Account Balance      | Bad Request  | 400        | Insufficient Account Balance to process request. Contact Quantiv Admin. |


Version: 1.0.0

## Servers

```
https://public-api.quantiv.io
```

## Download OpenAPI description

[Quantiv API](https://docs.quantiv.io/_spec/API/openapi.yaml)

## Lead Append Level 1

Method to retrieve property details based on the provided information.

**Note:** If any parameter in the response contains a `null` value, it indicates that the value could not be determined based on the provided data.


### Get Lead Property Details

 - [GET /api/v1/address-info](https://docs.quantiv.io/api/openapi/lead-append-level-1/paths/~1api~1v1~1address-info/get.md)

## Lead Append Level 2

Method to retrieve property details, Lead Integrity Score and Defects based on the provided information. 

**Note:** If any parameter in the response contains a `null` value, it indicates that the value could not be determined based on the provided data.

**Lead Integrity Score** indicates the quality of a lead based on various factors such as zoning classification, owner occupancy status, presence of a structure, and surname match. It helps assess the reliability of a lead.


**Score Values**
| Score | Quality Level | Description |
|-------|--------------|-------------|
| null  | Unknown      | Lead quality can not be determined.| 
| 10–9  | Outstanding  | Highest lead quality. |
| 8–7   | Strong       | Reliable lead. |
| 6–5   | Moderate     | Average lead quality. |
| 4–3   | Weak         | Low-quality lead. |
| 2–1   | Very Weak    | Very low lead quality. |
| 0     | Unreliable   | Untrustworthy lead. |    

<br>          

**Lead Integrity Defects** indicates which factors contributed to a lower Lead Integrity Score. These defects highlight potential issues with the lead's reliability.

**Defect Values**
| Defect    | Description |
|----------|-------------|
| null     | Lead Defects can not be determined.|
| zoning   | Property type is not confirmed as residential. |
| occupancy | Property is not confirmed as occupied by the owner. |
| structure | Structure is not confirmed as present at the address. |
| surname  | Surname is not confirmed to match one of the names on the deed. |


### Get Lead Property Details

 - [GET /api/v1/address-info-v2](https://docs.quantiv.io/api/openapi/lead-append-level-2/paths/~1api~1v1~1address-info-v2/get.md)

## Buyer Insights

**Buyer Insights** is a comprehensive suite of scoring tools designed to help home services providers assess homeowners' financial reliability, purchasing behavior, and willingness to invest in premium home improvements. It includes:

- **SurePay™ Score** – Evaluates the likelihood of homeowners paying for services, helping contractors mitigate financial risk.  
- **Elevate Score** – Measures a homeowner’s receptiveness and financial ability to invest in upsell opportunities and higher-end home improvements.
- **Buyer Insights Scores** – Assesses consumer buying styles across various categories.   
- **Sales Hacks** – Delivers instant, actionable guidance by translating Buyer Insights, SurePay™, and Elevate Scores into practical sales strategies for more effective customer engagement. 
- **Property Details**: Contextual address information to support sales, site assessment, and project planning. Refer to [Lead Append Level 2 Documentation](https://docs.quantiv.io/api/lead-append-level-2).
- **Lead Integrity Score and Defects**: Measures to ensure data reliability and lead quality. Refer to [Lead Append Level 2 Documentation](https://docs.quantiv.io/api/lead-append-level-2).

 Buyer Insights empowers businesses with data-driven insights, enabling smarter decision-making and improved profitability.

 **Note:** If any parameter in the response contains a `null` value, it indicates that the value could not be determined based on the provided data.
 
 **SurePay™ Score Values**
| Value | Description |
|-------|------------|
| null  | Score can not be determined. |
| 5     | High likelihood to perform and meet obligations. High likelihood to qualify for the best interest rates. |
| 4     | Likely to perform and meet obligations. Likely to qualify for most loans at slightly higher rates. |
| 3     | Average likelihood to perform and meet obligations. May qualify for some loans at higher rates. |
| 2     | Poor likelihood to perform and meet obligations. May qualify for some loans at significantly higher rates. |
| 1     | Unlikely to perform and meet obligations. Highly unlikely to qualify for any loans. |

<br>

**Elevate Score Values**
| Value  | Description           |
|--------|-----------------------|
| null   | Score can not be determined. |
| 10     | Extremely Likely      |
| 9      | Highly Likely         |
| 8      | Very Likely           |
| 7      | Somewhat Likely       |
| 6      | Likely                |
| 5      | Somewhat Unlikely     |
| 4      | Very Unlikely         |
| 3      | Highly Unlikely       |
| 1-2    | Extremely Unlikely    |

<br>

**Buyer Insights Scores Description**
| Score                  | Description |
|------------------------|-------------|
| **Savvy Shopper**      | **Rationale**: These homeowners conduct extensive research and compare multiple options—not necessarily to find the lowest price, but to ensure they make a well-informed, risk-averse decision. These consumers like to compare prices across different sites before purchasing and typically read online reviews and consumer reports. **Sales Approach**: Build trust by offering side-by-side comparisons, testimonials, and third-party validations. Reinforce their ability to make an educated decision while subtly guiding them toward your best offering. |
| **Brand Loyalist**     | **Rationale**: These homeowners have strong brand preferences and believe that reputation equates to reliability. They may challenge recommendations that deviate from their preselected brands. These consumers are willing to pay more for proven and reputable brands. **Sales Approach**: Align with their existing knowledge by reinforcing brand credibility. Emphasize manufacturer warranties, certifications, and brand-backed guarantees. If proposing alternatives, focus on comparable or superior features rather than price. Educate the consumer about the brand if you sell a product in which brand awareness is limited. |
| **Trendsetter**        | **Rationale**: These homeowners love being ahead of the curve and are eager to explore innovative, cutting-edge solutions. They value exclusivity and uniqueness in their purchases. These consumers are trendsetters and early adopters of new products. **Sales Approach**: Present the newest, most innovative products first. Emphasize exclusivity, technological advancements, and the opportunity to be among the first to own the latest home improvement solutions. |
| **Budget-Savvy Buyer** | **Rationale**: These homeowners prioritize affordability and perceived value over brand reputation. They tend to emphasize cost-efficiency in their decision-making process. Price is more important to these consumers than brand name. **Sales Approach**: Present cost-effective solutions that maximize value. Highlight financing options, cost savings over time, and product benefits that justify the investment. Be prepared to handle objections related to pricing. |
| **Quality First Buyer** | **Rationale**: These buyers prioritize durability, craftsmanship, and peace of mind over price but may struggle to define what “quality” looks like. Quality matters for these consumers, and they are willing to pay more for fresh ingredients, durable materials, and quality craftsmanship. **Sales Approach**: Focus on quality differentiators such as superior materials, expert installation, and longevity. Help them visualize potential risks of choosing lower-quality options and reassure them of the long-term value. |
| **Impulse Shopper (Can’t Say No)** | **Rationale**: These homeowners are easily persuaded to add features or upgrades that enhance functionality or perceived value. These spenders find it difficult to say 'no' to things that catch their eyes. They recognize they are "spenders" rather than "savers" and appreciate a convenient purchase opportunity. Top of mind = In the cart.  **Sales Approach**: Strategically introduce upgrades and enhancements throughout the conversation. Highlight benefits of add-ons in a way that makes them feel essential rather than optional. Use visual demonstrations to reinforce desirability. |
| **Popular Picks**      | **Rationale**: These buyers seek social validation and prefer solutions that align with current trends and widely accepted choices. Online reviews and recommendations influence them significantly. **Sales Approach**: Leverage social proof by showcasing positive customer testimonials, industry trends, and best-selling options. Reinforce that their decision aligns with what other satisfied homeowners are choosing. |

<br>

**Buyer Insights Values**
| Value  | Description           |
|--------|-----------------------|
| null   | Score can not be determined. |
| 10     | Extremely Likely      |
| 9      | Highly Likely         |
| 8      | Very Likely           |
| 7      | Somewhat Likely       |
| 6      | Likely                |
| 5      | Somewhat Unlikely     |
| 4      | Very Unlikely         |
| 3      | Highly Unlikely       |
| 2      | Extremely Unlikely    |
| 1      | Unknown               |

  **Note:** Sales Hack value is provided for a Buyer Insight only when the related Buyer Insight Score meets or exceeds 8.

<br>

**Accuracy Code**

The accuracy code specifies the level at which the provided scores are categorized, 
based on the quality and relevance of the user-supplied data. It indicates the reference 
point used to generate the insights.
| Value  | Description           |
|--------|-----------------------|
| P      | The scores are directly related to the individual (owner) of the address, based on the provided address data. |
| A      | The scores are directly related to a primary member of the household associated with the address, based on the provided address data.|
| G      | The scores reflect the modeled profile of the homeowner based on the typical profile of owners within a narrow geographic area of the provided address data.|
| N      | No relevant data could be matched based on the provided information.|


### Get Buyer Insights

 - [GET /api/v1/buyer-insights](https://docs.quantiv.io/api/openapi/buyer-insights/paths/~1api~1v1~1buyer-insights/get.md)

## Lead Value - Roof

The **Lead Value - Roof API** is a fast, reliable tool for instantly assigning a value to roof replacement leads by calculating the approximate roof area and replacement costs based solely on a property address. Built specifically for roofing contractors, home improvement platforms, and sales engagement tools, it supports top-of-funnel lead generation and enables sales teams to quickly assess project value and prioritize opportunities.

The API processes address-level inputs and optional parameters like roof material and installation pricing per square — to return a detailed approximation that includes roof area (adjusted for pitch), average pitch angle, complexity level, and total estimated replacement cost.

The **Lead Value - Roof API** is designed to deliver consistent, data-backed approximations in real time — not to replace on-site inspections, precise measurements, or detailed proposals. Instead, it equips sales teams with a scalable, automated way to qualify and value leads.  By providing relative cost estimates early in the sales cycle, businesses can increase quote-to-close rates, reduce time spent on manual assessments, and focus efforts on the highest-value opportunities.

**Note:** If any parameter in the response contains a `null` value, it indicates that the value could not be determined based on the provided data.

**Structure Present Confidence Score Values**

| Value | Description |
|-------|-------------|
| null  | Value could not be determined. |
| 100   | High confidence that rooftop data corresponds to the primary structure at the exact address provided. |
| 50    | Data may correspond to a nearby structure rather than the actual address, indicating a possible issue with the input address. |

<br>

**When a Score of 50 is Returned**

A confidence score of 50 may be returned under the following conditions:

- No structure exists at the provided address (e.g., empty lot, typo in house number, or unvalidated address).
- Our system interpolated coordinates to the closest known structure due to an invalid or unrecognized address.
- Our system failed to detect a structure due to:
  - Recent new construction not yet reflected in mapping data
  - Street name formatting issues (e.g., uncommon abbreviations or casing)
  - Address formatting discrepancies that prevented structure identification

In such cases, the rooftop data returned may not represent the structure located at the submitted address.

**Data Accuracy Alerts**

The `Roof Pitch Alert` and `Roof Area Alert` parameters help identify potentially unreliable or atypical measurement results related to roof pitch or area. These alerts are designed to prompt additional validation or inspection.

**Roof Pitch Alert Values**

Indicates potential issues with roof pitch estimation.

| Value      | Description                                                                  |
|------------|------------------------------------------------------------------------------|
| null       | Value could not be determined.                                               |
| NO_ALERTS  | No pitch-related alerts detected.                                            |
| LOW_PITCH  | Detected pitch is unusually low — possibly due to flat roofs or obstruction. |
| HIGH_PITCH | Detected pitch is unusually high — may indicate steep or complex geometry.   |

<br>

**Roof Area Alert Values**

Indicates potential issues with roof area estimation.

| Value      | Description                                                                 |
|------------|-----------------------------------------------------------------------------|
| null       | Value could not be determined.                                              |
| NO_ALERTS  | No area-related alerts detected.                                            |
| LOW_AREA   | Estimated area is smaller than expected — may be caused by occlusion or missing imagery. |
| HIGH_AREA  | Estimated area is larger than expected — could result from multiple structures or over-segmentation. |

<br>

**When Alerts Are Triggered**

Alerts are generated to assist in identifying potentially inaccurate or atypical results based on the roof pitch or area. Common scenarios include:

- **Obstructed View**: Tree canopy, overhangs, or neighboring structures may obscure full visibility of the rooftop.
- **Imagery Quality**: Satellite or aerial images may be affected by shadows, poor lighting, or resolution issues.
- **Roof Complexity**: Irregular or highly complex roof geometries can make measurement modeling less reliable.
- **Multiple Structures**: Properties with multiple buildings or large accessory structures may lead to elevated or ambiguous area calculations.
- **Partial or Missing Imagery**: Incomplete or outdated imagery data can lead to pitch or area deviations.

In such cases, alerts provide a useful prompt for further validation, helping to prioritize follow-up review and ensure more accurate project planning.

### Get Lead Value - Roof

 - [GET /api/v1/roof-estimate](https://docs.quantiv.io/api/openapi/lead-value-roof/paths/~1api~1v1~1roof-estimate/get.md)

## GoSolar Index


**GoSolar Index** is an analytics tool built exclusively for residential solar sales teams, CRM platforms, and App providers to optimize lead qualification and targeting. This powerful scoring feature combines **behavioral signals**, **sustainability intent**, **financial indicators**, **and political orientation** to deliver a **single**, **predictive score** for every homeowner, improving conversion rates by identifying high-propensity targets.  

The API response includes:
 - **GoSolar Index Score (10–0)**: A quantitative indicator of solar adoption potential.
 - **Prospect Fit Level**: A qualitative assessment (Ideal, Moderate, Weak) for quick segmentation.
 - **Prospect Attitude Message**: An insight into the homeowner’s likely solar motivation, such as environmental, sustainability, economic, or energy independence, enabling tailored messaging.
 - **Property Details**: Contextual address information to support sales, site assessment, and project planning. Refer to [Lead Append Level 2 Documentation](https://docs.quantiv.io/api/lead-append-level-2).
 - **Lead Integrity Score and Defects**: Measures to ensure data reliability and lead quality. Refer to [Lead Append Level 2 Documentation](https://docs.quantiv.io/api/lead-append-level-2).

Solar providers can integrate the **GoSolar Index** into their lead scoring systems to improve conversion rates, reduce outreach costs, and personalize customer engagement strategies. 

**Note:** If any parameter in the response contains a `null` value, it indicates that the value could not be determined based on the provided data.

**GoSolar Index and Prospect Fit Level Mapping**
| GoSolar Index   | Prospect Fit Level                                                                |
 |------------|-----------------------------------------------------------------------------|
 | 8.33 – 10  | Ideal                                       |
 | 5.0 – 8.32   | Moderate |
 | 0 – 4.99  | Weak |

<br>

**Prospect Attitude Message Values**
 |  |
 |------------|
 | Lead with emphasis on climate, sustainability, and clean energy considerations. |
 | Lead with emphasis on economic benefits, incentives, energy independence, and ROI consideration.  |
 | Neutral message emphasizing both economic benefits, incentives, independence and renewable energy benefits, and sustainability. |

<br>
 
**Accuracy Code**

The accuracy code specifies the level at which the provided response is
categorized, based on the quality and relevance of the user-supplied data. It indicates the reference point used to generate the insights.
 | Value  | Description|
 |--------|------------|
 | P      | `GoSolar Index`, `Prospect Fit Level` and `Prospect Attitude Message` are directly related to the individual (owner) of the address, based on the provided address data.|
 | A      | `GoSolar Index`, `Prospect Fit Level` and `Prospect Attitude Message` are directly related to a primary member of the household associated with the address, based on the provided address data.|
 | G      | `GoSolar Index`, `Prospect Fit Level` and `Prospect Attitude Message` reflect the modeled profile of the homeowner based on the typical profile of owners within a narrow geographic area of the provided address data.|
 | N      | No relevant data could be matched based on the provided information.|  

### Get GoSolar Index

 - [GET /api/v1/gosolar-index](https://docs.quantiv.io/api/openapi/gosolar-index/paths/~1api~1v1~1gosolar-index/get.md)

## Utility Bill

The **Utility Bill API** provides accurate energy usage on an address-specific basis without a utility bill. The API responds with electricity and fossil fuel consumption and cost data for the past 12 months. This information is especially valuable for solar salespeople, enabling them to obtain instant energy consumption data and cost per kilowatt hour (kWh) to utilize in initial estimates and proposals before requesting or receiving a homeowner’s utility bill.

**Key Features:**
- Monthly, quarterly, and annual electricity consumption and cost breakdown, including electricity utility rate.
- Emissions data and CO₂ analytics related to electricity usage.
- Fossil fuel usage statistics including cost, type, and utility rate.
- Ratio analysis between electricity and fossil fuel consumption.

The response includes a `electricToFossilRatio` field representing the ratio of electricity usage to fossil fuel usage over the last 12 months. 
- If a home has a ratio less than 1, it indicates the home consumes more fossil fuel than electricity.
- If a home uses only electricity and no fossil fuels, the ratio value will be `null`.

The API responds with a structured summary of utility usage or a message indicating that no valid data is available for the given address.

### Get Utility Bill Information

 - [GET /api/v1/utility-bill](https://docs.quantiv.io/api/openapi/utility-bill/paths/~1api~1v1~1utility-bill/get.md)

## EngagePro™ - Lead Widget

The **Quantiv's EngagePro™ - Lead Widget** is a lightweight, high-converting widget designed to help CRM and App Providers enable their Clients to generate qualified roofing leads effortlessly.

The widget can be launched:
- As an overlay popup on the Client’s website via the Widget Script
- As a hosted flow on a Quantiv-managed domain
- Via shareable QR codes and direct links (great for digital and offline use)

Homeowners receive an instant roofing estimate in under 30 seconds while Clients collect detailed lead information — all fully branded.

Clients can fully customize both the widget UI element (button, banner, or custom) and the appearance of the full flow by:
- Uploading logos
- Setting brand colors (primary, secondary, background, text, links)
- Defining company info, terms of use, and privacy policy links
- Setting installation price used in roof cost estimation
- Updating the title of the first screen

The API allows CRM and App Providers to offer their Clients full control over widget creation, activation, and management directly from their own UI/UX — while Quantiv handles hosting, script generation, QR codes, and link creation.

Check out the [Widgets detailed documention](/LeadGenWidget/overview.md) for more information.


### Create EngagePro™ - Lead Widget

 - [POST /api/v1/roof-estimate-widget](https://docs.quantiv.io/api/openapi/engageprotm-lead-widget/paths/~1api~1v1~1roof-estimate-widget/post.md): Creates the EngagePro™ - Lead Widget configuration.

### Update EngagePro™ - Lead Widget

 - [PUT /api/v1/roof-estimate-widget/{referenceId}](https://docs.quantiv.io/api/openapi/engageprotm-lead-widget/paths/~1api~1v1~1roof-estimate-widget~1%7Breferenceid%7D/put.md): Updates the EngagePro™ - Lead Widget configuration.

### Retrieve EngagePro™ - Lead Widget

 - [GET /api/v1/roof-estimate-widget/{referenceId}](https://docs.quantiv.io/api/openapi/engageprotm-lead-widget/paths/~1api~1v1~1roof-estimate-widget~1%7Breferenceid%7D/get.md): Retrieves the EngagePro™ - Lead Widget configuration.

## Widget Webhooks

Quantiv supports webhook integrations to notify CRM and App Providers in real time about critical events related to the EngagePro™ - Lead Widget.

These webhooks enable your systems to:
- React to key lifecycle events such as widget creation and updates.
- Track lead creation and changes as users interact with the EngagePro™ - Lead Widget.
- Power internal automations, analytics, and client communication.

Webhooks are delivered via HTTPS as JSON payloads and are triggered for the following events:
- `lead.created`
- `lead.updated`
- `widget.created`
- `widget.updated`

Webhooks can be registered, updated, retrieved, or deleted using the provided API methods. Each webhook includes metadata such as success/failure counts and timestamps of the last invocation attempts.


Check out our [Webhook guide](/LeadGenWidget/webhooks.md) for more information.

### Create New Webhook

 - [POST /api/v1/webhooks](https://docs.quantiv.io/api/openapi/widget-webhooks/paths/~1api~1v1~1webhooks/post.md): Creates a webhook to listen for events related to widgets.

### List All Webhooks

 - [GET /api/v1/webhooks](https://docs.quantiv.io/api/openapi/widget-webhooks/paths/~1api~1v1~1webhooks/get.md): Retrieves all created webhooks.

### Update Existing Webhook

 - [PATCH /api/v1/webhooks/{webhookId}](https://docs.quantiv.io/api/openapi/widget-webhooks/paths/~1api~1v1~1webhooks~1%7Bwebhookid%7D/patch.md): Updates existing webhook.

### Delete Existing Webhook

 - [DELETE /api/v1/webhooks/{webhookId}](https://docs.quantiv.io/api/openapi/widget-webhooks/paths/~1api~1v1~1webhooks~1%7Bwebhookid%7D/delete.md): Deletes existing webhook.