Modernize Home Services Ping Post API

This document contains detailed instructions and examples for how to sell leads to Modernize Home Services through our Ping Post web API, using a two-step process known as "Ping/Post."

All material confidential. Materials constitute proprietary information of Modernize Home Services and QuinStreet, Inc. and may be used by the recipient solely to evaluate an existing business relationship with Modernize Home Services. All other rights reserved by Modernize Home Services.

Contents:

How It Works

Ping/Post is a two-step process:

1. Ping - You offer a lead to us by first sending our API partial information about the lead, e.g., service and zipcode. We respond, indicating whether we can buy the lead and for how much ($).
2. Post - You send us the full details of the lead. We respond, confirming receipt. If the lead is a duplicate or invalid lead, we return an error response indicating the reason.

Details for each step are explained in-depth below.

Before You Start

Before you start sending leads, you will need the following:

• An active QuinStreet publisher account
• Authorization for the service(s) for which you wish to sell us leads
• tagId, to be used in your production API requests (see below)

Environments

Modernize hosts two API environments, one for production operations and another for testing:

The Staging environment is for testing. No staging environment leads will be billable.

IMPORTANT: Before sending real leads to the Production environment, you must first test using the Staging environment. Doing so verifies that you are correctly authenticating, formatting data fields, and authorized to send us leads for your given service(s). Once you have tested and determined that everything is behaving as expected on the Staging environment, you can move to the Production environment.

Ping

Use the following HTTP API to offer a lead for sale to Modernize by sending partial information about the lead.

Post

Use the following API after a successful Ping response (see above) to transact a sale of a lead to Modernize Home Services, by sending full details the lead along with a PingToken.

Common Parameters [CASE-SENSITIVE]

Unless otherwise indicated, the parameters below are accepted for all services.

IMPORTANT:

• All keys and values are CASE-SENSITIVE. If you use different casing, the key or value may be treated as invalid. E.g., use OwnHome=Yes, not ownhome=yes.
• Keys and values must be encoded in key-value pairs separated by &, with a = between the key and the value.
• Non-alphanumeric characters in both keys and values must be URL-Encoded.

* A compliance certification token is required on all leads. You must pass either or both of LeadIDToken (Jornaya) or TrustedFormToken (ActiveProspect) for a lead to be accepted.

Service-Specific Parameters [CASE-SENSITIVE]

IMPORTANT: All parameters and values are CASE-SENSITIVE. If you pass incorrectly cased parameters or values, they may be treated as invalid

The following parameters should be used on BOTH Ping and Post requests for the service indicated. If Parameter Name is N/A below, no additional parameters are required for the service.

Common Services

Other Services

Examples

Ping Examples

Example Ping Request:

POST /modernize/coreg/hsleadcapture HTTP/1.1
    Host: https://example.leadprosper.tech
    Content-Type: application/x-www-form-urlencoded
    Content-Length: 350

    pingType=v2&tagId=204670250&service=WINDOWS&PC=99751&NumberOfWindows=6-9&WindowsProjectScope=Install&BuyTimeframe=Immediately&OwnHome=Yes&HomePhoneConsent=Yes&LeadIDToken=EAF0AAF2-55CD-08A7-DE78-C5A090B3A57B&TrustedFormToken=https%3A%2F%2Fcert.trustedform.com%2F5d9f37382eca1518c752db469cacb6668049c8d3&PublisherSubID=123456&PartnerSourceID=CampaignA
    

Example Ping Response - Success:

200 OK
    {
        "STATUS":"SUCCESS",
        "PINGTOKEN":"50108462152",
        "PRICE":"50"
    }
    

Example Ping Response - Unmatched:

200 OK
    {
        "STATUS":"REJECTED"
    }
    

Example Error Response - Not Authorized for Service:

200 OK
    {
        "STATUS":"ERROR",
        "VALIDATION MESSAGE":"900- Service/Pricing not setup - please contact your account representative."
    }
    

Post Examples

Example Post Request (newline characters shown for clarity):

POST /modernize/coreg/hsleadcapture HTTP/1.1
    Host: https://example.leadprosper.tech
    Content-Type: application/x-www-form-urlencoded
    Content-Length: 522

    PingToken=50108510154&tagID=204670250&service=WINDOWS&PC=99751&NumberOfWindows=6-9&WindowsProjectScope=Install&BuyTimeframe=Immediately&OwnHome=Yes&LeadIDToken=EAF0AAF2-55CD-08A7-DE78-C5A090B3A57B&TrustedFormToken=https%3A%2F%2Fcert.trustedform.com%2F5d9f37382eca1518c752db469cacb6668049c8d3&PublisherSubID=123456&PartnerSourceID=CampaignA&HomePhoneConsentLanguage=Fake%20example%20I%20consent%20to%20receiving%20calls%20etc.&FN=Quin&LN=Street&S1=9305%20Nimbus%20Ave&CT=Kobuk&SP=AK&HP=5039065030&EM=bizdev%40quinstreet.com
    

Example Post Response - Accepted:

200 OK
    {
        "STATUS":"ACCEPTED",
        "GDCKEY":"10221479803"
    }
    

Example Post Response - Rejected for Validation Failure:

200 OK
    {
        "STATUS":"REJECTED",
        "VALIDATIONMESSAGE":"Lead is failed in Targus Validations"
    }
    

Example Post Response - Rejected for Vendor Duplicate

200 OK
    {
        "STATUS":"REJECTED",
        "VALIDATIONMESSAGE":"Lead already submitted for the vendors matched"}
    }
    

Example Post Response - Error, Invalid Zip

200 OK
    {
        "STATUS":"REJECTED",
        "VALIDATION MESSAGE":"Lead is rejected",
        "ERRORS":[
            "Invalid Zip Code"
        ]
    }
    

Example Post Response - Error, Invalid Service

200 OK
    {
        "STATUS":"REJECTED",
        "VALIDATION MESSAGE":"Lead is rejected",
        "ERRORS":[
            "Please fix the service code: WAS"
        ]
    }
    

Response & Error Codes

Ping

Post

Additional Tips

tagId Field

The tagId is unique to your publisher account and authorizes you to send leads for particular services. tagID=204670250 is used only for the Staging environment. Once we confirm stage tests and you move to using the production API, this value must be replaced with the tagID value given to you by your account manager. NOTE: Test submissions are not billable.

pingType and PingToken Fields

• pingType=v2 must ONLY be passed on Ping requests. It is the field that differentiates Ping requests from Post requests. Make sure the parameter is NOT included with your Post.
• Make sure to grab the PingToken from the Ping response to put in the Post request as instructed in Common Parameters.

TCPA Consent

• On Ping, pass HomePhoneConsent=Yes indicating that your user saw consent.
• On Post, pass HomePhoneConsentLanguage=<...>, including the full language that was shown to the user on-site, in URL-encoded form. Do NOT pass HomePhoneConsent=Yes. Please ask your account manager for details on what exact language we accept.

Compliance Certification Token

• You must ALWAYS pass an ActiveProspect certificate token in the TrustedFormToken field.
• Some services additionally require a Jornaya certificate, whose token must be passed in the LeadIDToken field. Check with your account manager if there are any issues.
• Pass the TrustedFormToken and LeadIDToken on both Ping and Post requests.