openapi: 3.0.0
info:
  title: Quantiv API
  version: 1.0.0
  description: >
    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.


    ### 🚀 Getting Started
      
      To get started with Quantiv API Products you will need to follow these steps:
        1. Contact the Quantiv representative via [our website](https://www.quantiv.io).
        2. Sign an agreement with Quantiv.
        3. Receive your sandbox and production API keys.
        4. Receive an invite to the Customer Portal, where you can track API usage and billing details.

    ### 🌐 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. |
  termsOfService: https://www.quantiv.io/terms-of-service
  contact:
    email: eugene@quantiv.io
servers:
  - url: https://public-api.quantiv.io
tags:
  - name: Lead Append Level 1
    description: |
      Method to retrieve property details based on the provided information.
  - name: Lead Append Level 2
    description: >
      Method to retrieve property details, Lead Integrity Score and Defects
      based on the provided information. 


      **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. |
  - name: Buyer Insights
    description: >
      **Bayer 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 upsell opportunities and higher-end home improvements.

      - **Buyer Insights Scores** – Assesses consumer buying styles across
      various categories.    

       Buyer Insights empowers businesses with data-driven insights, enabling smarter decision-making and improved profitability.
       
       **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               |


      <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.|
paths:
  /api/v1/address-info:
    get:
      tags:
        - Lead Append Level 1
      summary: Get Lead Property Details
      parameters:
        - name: Accept
          in: header
          schema:
            type: string
          example: application/json
        - name: token
          in: header
          schema:
            type: string
          example: '{API Key}'
        - name: streetNumber
          in: query
          required: true
          schema:
            type: string
          description: Lead's street number.
        - name: streetAddress
          in: query
          required: true
          schema:
            type: string
          description: Lead's street address.
        - name: city
          in: query
          required: true
          schema:
            type: string
          description: Lead’s city name.
        - name: state
          in: query
          required: true
          schema:
            type: string
          description: Lead's state name (two-letter abbreviation, e.g., NY).
        - name: zip
          in: query
          required: false
          schema:
            type: string
          description: Lead’s zip code (5 digit code).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    example: '2024-08-20T14:30:00Z'
                    description: >-
                      The timestamp when the response was returned. It is
                      provided in ISO 8601 format.
                  primaryOwner:
                    type: string
                    nullable: true
                    example: John M Doe
                    description: Full name of the primary owner.
                  secondaryOwner:
                    type: string
                    nullable: true
                    example: Jane Doe
                    description: Full name of the secondary owner.
                  ownerOccupied:
                    type: boolean
                    nullable: true
                    example: true
                    description: Indicates whether the property is occupied by the owner.
                  homeBuiltYear:
                    type: string
                    nullable: true
                    example: '1990'
                    description: The year the primary structure was built.
                  yearsInHome:
                    type: string
                    nullable: true
                    example: '16'
                    description: >-
                      The number of years the primary owner has owned the
                      property.
                  county:
                    type: string
                    nullable: true
                    example: Douglas
                    description: County name.
                  subdivision:
                    type: string
                    nullable: true
                    example: Castle Oaks
                    description: Subdivision name.
                  school:
                    type: string
                    nullable: true
                    example: Somerville
                    description: School district name.
                  propertyType:
                    type: string
                    nullable: true
                    example: Residential
                    description: General property type description.
                  areaBuildingSize:
                    type: string
                    nullable: true
                    example: '3023'
                    description: Total square feet of all structures on the property.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
                  statusCode:
                    type: integer
                    example: 400
                  message:
                    type: array
                    items:
                      type: string
                    example:
                      - state must be a string
                      - state should not be empty
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  statusCode:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: Invalid API Key
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
                  statusCode:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Cannot GET /api/v1/address-info
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal Server Error
                  statusCode:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Unexpected server error occurred. Please try again later.
  /api/v1/address-info-v2:
    get:
      tags:
        - Lead Append Level 2
      summary: Get Lead Property Details
      parameters:
        - name: Accept
          in: header
          schema:
            type: string
          example: application/json
        - name: token
          in: header
          schema:
            type: string
          example: '{API Key}'
        - name: streetNumber
          in: query
          required: true
          schema:
            type: string
          description: Lead's street number.
        - name: streetAddress
          in: query
          required: true
          schema:
            type: string
          description: Lead's street address.
        - name: city
          in: query
          required: true
          schema:
            type: string
          description: Lead’s city name.
        - name: state
          in: query
          required: true
          schema:
            type: string
          description: Lead's state name (two-letter abbreviation, e.g., NY).
        - name: zip
          in: query
          required: false
          schema:
            type: string
          description: Lead’s zip code (5 digit code).
        - name: lastName
          in: query
          required: false
          schema:
            type: string
          description: Lead’s last name. Used for Lead Integrity Score calculation.
        - name: leadIntegrityScoreOn
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            Used for activating Lead Integrity information being returned in
            response.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    example: '2024-08-20T14:30:00Z'
                    description: >-
                      The timestamp when the response was returned. It is
                      provided in ISO 8601 format.
                  primaryOwner:
                    type: string
                    nullable: true
                    example: John M Doe
                    description: Full name of the primary owner.
                  secondaryOwner:
                    type: string
                    nullable: true
                    example: Jane Doe
                    description: Full name of the secondary owner.
                  ownerOccupied:
                    type: boolean
                    nullable: true
                    example: true
                    description: Indicates whether the property is occupied by the owner.
                  homeBuiltYear:
                    type: string
                    nullable: true
                    example: '1990'
                    description: The year the primary structure was built.
                  yearsInHome:
                    type: string
                    nullable: true
                    example: '16'
                    description: >-
                      The number of years the primary owner has owned the
                      property.
                  county:
                    type: string
                    nullable: true
                    example: Douglas
                    description: County name.
                  subdivision:
                    type: string
                    nullable: true
                    example: Castle Oaks
                    description: Subdivision name.
                  school:
                    type: string
                    nullable: true
                    example: Somerville
                    description: School district name.
                  propertyType:
                    type: string
                    nullable: true
                    example: Residential
                    description: General property type description.
                  areaBuildingSize:
                    type: string
                    nullable: true
                    example: '3023'
                    description: Total square feet of all structures on the property.
                  scructurePresent:
                    type: boolean
                    nullable: true
                    example: true
                    description: >-
                      Indicates whether the structure is present at the provided
                      address.
                  leadIntegrityScore:
                    type: integer
                    nullable: true
                    example: 7
                    description: >-
                      Indicates lead’s quality. Evaluates such parameters, as
                      zoning classification, owner occupied, structure present,
                      surname match. The parameter is returned if
                      `leadIntegrityScoreOn` parameter = true in query.
                  leadIntegrityDefects:
                    type: array
                    nullable: true
                    items:
                      type: string
                    example:
                      - surname
                    description: >-
                      Indicates lead’s quality. Evaluates such parameters, as
                      zoning classification, owner occupied, structure present,
                      surname match. The parameter is returned if
                      `leadIntegrityScoreOn` parameter = true in query.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
                  statusCode:
                    type: integer
                    example: 400
                  message:
                    type: array
                    items:
                      type: string
                    example:
                      - state must be a string
                      - state should not be empty
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  statusCode:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: Invalid API Key
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
                  statusCode:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Cannot GET /api/v1/address-info-v2
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal Server Error
                  statusCode:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Unexpected server error occurred. Please try again later.
  /api/v1/buyer-insights:
    get:
      tags:
        - Buyer Insights
      summary: Get Buy Insights Scores
      parameters:
        - name: Accept
          in: header
          schema:
            type: string
          example: application/json
        - name: token
          in: header
          schema:
            type: string
          example: '{API Key}'
        - name: streetNumber
          in: query
          required: true
          schema:
            type: string
          description: Lead's street number.
        - name: streetAddress
          in: query
          required: true
          schema:
            type: string
          description: Lead's street address.
        - name: city
          in: query
          required: true
          schema:
            type: string
          description: Lead’s city name.
        - name: state
          in: query
          required: true
          schema:
            type: string
          description: Lead's state name (two-letter abbreviation, e.g., NY).
        - name: zip
          in: query
          required: false
          schema:
            type: string
          description: Lead’s zip code (5 digit code).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    example: '2024-08-20T14:30:00Z'
                    description: >-
                      The timestamp when the response was returned. It is
                      provided in ISO 8601 format.
                  surepay_score:
                    type: integer
                    nullable: true
                    example: 1
                    description: Represents SurePay™ Score.
                  elevate_score:
                    type: integer
                    nullable: true
                    example: 2
                    description: Represents Elevate Score.
                  buyer_insights:
                    type: object
                    properties:
                      savvy_shopper_score:
                        type: integer
                        nullable: true
                        description: Score for Savvy Shopper category.
                        example: 2
                      brand_loyalist_score:
                        type: integer
                        nullable: true
                        description: Score for Brand Loyalist category.
                        example: 3
                      trendsetter_score:
                        type: integer
                        nullable: true
                        description: Score for Trendsetter category.
                        example: 3
                      budgetsavvy_buyer_score:
                        type: integer
                        nullable: true
                        description: Score for Budget-Savvy Buyer category.
                        example: 4
                      quality_first_buyer_score:
                        type: integer
                        nullable: true
                        description: Score for Quality First Buyer category.
                        example: 0
                      impulse_shopper_score:
                        type: integer
                        nullable: true
                        description: Score for Impulse Shopper category.
                        example: 1
                      popular_picks_score:
                        type: integer
                        nullable: true
                        description: Score for Popular Picks category.
                        example: 5
                  owner_full_name:
                    type: string
                    nullable: true
                    example: John Doe
                    description: Indicates address owner full name.
                  accuracy_code:
                    type: string
                    example: P
                    description: Represents Accuracy Code.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
                  statusCode:
                    type: integer
                    example: 400
                  message:
                    type: array
                    items:
                      type: string
                    example:
                      - state must be a string
                      - state should not be empty
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  statusCode:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: Invalid API Key
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
                  statusCode:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Cannot GET /api/v1/buyer-insights
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal Server Error
                  statusCode:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Unexpected server error occurred. Please try again later.
components: {}
