Ping Post v3 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.”

Contents #

Document Revision: DRAFT Jan 2025

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.

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 of the lead along with a pingToken.

Common Parameters [CASE-SENSITIVE] #

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

* A compliance certification token is required for all leads. You must pass the trustedFormToken (ActiveProspect) for a lead to be accepted. The leadIDToken (Jornaya) may be passed along with the trustedFormToken but is not required.

Service-Specific Parameters [CASE-SENSITIVE] #

The following parameters are optional on the Post operation, unless otherwise indicated. Providing these additional parameters can help reduce the likelihood of a post reject occuring. If Parameter Name is N/A below, no additional parameters are required for the service.

IMPORTANT: PARAMETER NAMES HAVE CHANGED in our new API. Additionally, all keys and values are CASE-SENSITIVE AND MAY FOLLOW A DIFFERENT CASING CONVENTION. Some parameters follow the “camelCase”-style convention, while other may follow a “TitleCase”-style convention; E.g., use GuttersType, not guttersType. Please look closely at this document to understand the exact required names for parameters and their possible values. If you pass an invalid parameter name or value, your lead may be rejected.

Common Services #

Other Services #

Example #

Ping #

Example Ping Request:

POST /ping-post/pings HTTP/1.1
Host: <hostname>
Content-Type: application/json
{
    "tagId": "204670250",
    "service": "WINDOWS",
    "postalCode": "99751",
    "buyTimeFrame": "Immediately",
    "ownHome": "Yes"
}

Example Ping Response - Success:

201 Created
{
    "status":"success",
    "pingToken": "VBny1dlGo483ZVsJj24BW1xWpA0RrK5z",
    "price":"50",
    "message": null
}

Example Ping Response - Rejected

{
    "status":"rejected",
    "pingToken": null,
    "price": null,
    "message": null
}

Example Ping Response - Error

{
    "status":"error",
    "message": "postalCode is required." 
}

Post Lead #

Example Post Request (newline characters shown for clarity):

POST /ping-post/posts HTTP/1.1
Host: <hostname>
Content-Type: application/json
{
    "pingToken": "VBny1dlGo483ZVsJj24BW1xWpA0RrK5z",
    "tagId": "204670250",
    "service": "WINDOWS",
    "NumberOfWindows": "6-9",
    "WindowsProjectScope": "Install",
    "buyTimeframe": "Immediately",
    "ownHome": "Yes",
    "leadIDToken": "EAF0AAF2-55CD-08A7-DE78-C5A090B3A57B",
    "trustedFormToken": "https://cert.trustedform.com/5d9f37382eca1518c752db469cacb6668049c8d3",
    "publisherSubId": "123456",
    "partnerSourceId": "CampaignA",
    "firstName": "John",
    "lastName": "doe",
    "email": "john.doe@gmail.com",
    "phone": "5403216765",
    "state": "CA",
    "address": "1234 st",
    "postalCode": "99751",
    "homePhoneConsentLanguage": "Fake example I consent to receiving calls etc."
}

Example Post Response - Success:

201 Created
{
    "status": "success",
    "leadId": "50108462152",
    "message": null
}

Example Post Response - Rejected

{
    "status": "rejected",
    "message": "pingToken invalid/ pingToken expired",
    "leadId": null
}

Response & Error Codes #

Ping Errors #

Post Errors #

FAQ #

How long is a pingToken valid? #

While most posts are expected to be completed within a few minutes of the ping (typically 3 minutes or less), we understand that some consumers may take longer to finish their actions. Therefore, pingToken validity extends up to 30 minutes, accommodating these scenarios.

Appendix #

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.

TCPA Consent #

• On Post, pass "homePhoneConsentLanguage": "<...>", including the full language that was shown to the user on-site. 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 Post requests.

Successful Testing in Staging #

While integrating with the API in our staging environment you’ll need to test successful matches scenarios. To guarantee your testing lead matches with clients, you can use one of the following trade specific examples with either of the following postal codes.

Solar #

{
    "tagId": "204670250",
    "service": "SOLAR",
    "postalCode": "99004",
    "buyTimeframe": "Immediately",
    "ownHome": "Yes",
    "partnerSourceId" : "campaignA",
    "publisherSubId" : "123456678",
    "ElectricBill" : "$100 - $200"
}

Roofing #

{
    "tagId": "204670250",
    "service": "ROOFING_METAL", // ROOFING_COMPOSITE, ROOFING_ASPHALT, or 
    "postalCode": "84601",
    "buyTimeframe": "Immediately",
    "ownHome": "Yes",
    "partnerSourceId": "CampaignA",
    "publisherSubId" : "123456678",
    "RoofingPlan" : "Install roof on new construction"
}