Modernize v3 API Ping Post Buyer Setup

To get started, you’ll need a copy of your buyer’s API specs. For this example we are using the generic Ping Ping v3 API specs from Modernize which you can find here.

The Modernize v3 API specs are set up based on the SERVICE - and from there you are given Service-Specific Parameters that are required based on the Service selected. The table contains the "service" value in the first column, the service-specific parameters are in the second column, and the allowed values for the field are in the third column.

For this example we are going to be setting up the Buyer as a Windows buyer.

Service-Specific Parameters

The Modernize v3 API specs contain a table of fields that are going to be specific and required based on the 'service' value you choose. Different services have different Service-Specific Parameters so make sure you copy each

Let's take WINDOWS for example. If you are using "service":  "WINDOWS" the chart shows two additional required Service-Specific Parameters - NumberOfWindows and WindowsProjectScope.


You’ll begin by copying and pasting the PING URL into your Buyer setup and replacing <host> with the Staging/Test Environment. Once you’ve successfully tested your buyer and are ready to go live, you’ll replace this section or the URL with the Production Environment

Staging / Testing

PING URL: https://hsapiservice.quinstage.com/ping-post/pings

POST URL: https://hsapiservice.quinstage.com/ping-post/posts

Production

PING URL: https://form-service-hs.qnst.com/ping-post/pings

POST URL: https://form-service-hs.qnst.com/ping-post/posts

To begin setting up this buyer create a new buyer, and select Ping Post, and begin:

Step 1. PING Set Up

First step will be setting up your PING with the following:

PING Request


Example Windows PING Payload

Here is an example PING payload for Windows

{
"tagId": "204670250",
"service": "WINDOWS",
"postalCode": "28704",
"buyTimeFrame": "Immediately",
"ownHome": "Yes",
"trustedFormToken": "https://cert.trustedform.com/5d9f37382eca1518c752db469cacb6668049c8d3",
"publisherSubId": "123456",
"partnerSourceId": "LP_CAMPAIGN_A",
"NumberOfWindows": "6-9",
"WindowsProjectScope": "Install"
}

Required Fields

All field names and values are case sensitive, so copy and paste them directly from the specs

  • tagID : use Test tagID '204670250' during testing, Production tagID once live)
  • service : choose the correct service value from the list of COMMON SERVICES
  • postalCode : lead zip code, default campaign field is {{zip_code}}
  • buyTimeFrame : map to your timeframe campaign field, or hardcode a default value from this list - Immediately, 1-6 months, Don't know
  • ownHome : Yes or No . If not the owner, but is authorized to make improvements, use Yes
  • partnerSourceId : Value to identify campaigns by marketing efforts or channels on the publisher side. Helps Modernize track and report quality back to publisher
  • trustedFormToken : TrustedForm Cert URL. Your PING and POST must contain at least a TrusteForm Cert URL or a Jornaya LeadiD. It's suggested to collect and send both if possible.
  • leadIDToken : Jornaya LeadiD. Your PING and POST must contain at least a TrusteForm Cert URL or a Jornaya LeadiD. It's suggested to collect and send both if possible.
  • publisherSubId : Your own internal tracking ID. For a unique value for each lead you can use the system field {{lp_lead_id}}


PING Response Mapping

The PING Response Mapping for Modernize v3 will consist of 3 different settings - the Accepted Response Mapping, the Real-Time Pricing, and setting a custom variable to use on the POST for the pingToken value.

Success:

Condition: key equal with

Key: status

Value: success

Real-Time Price:

Value: price

Step 2. POST Set Up

POST Request


Example Windows POST Payload

Here is an example POST payload for Windows:

{
"pingToken": 
"tagId": "204670250",
"service": "WINDOWS",
"postalCode": "99751",
"buyTimeFrame": "Immediately",
"ownHome": "Yes",
"trustedFormToken": "https://cert.trustedform.com/5d9f37382eca1518c752db469cacb6668049c8d3",
"publisherSubId": "123456",
"partnerSourceId": "LP_CAMPAIGN_A",
"NumberOfWindows": "6-9",
"WindowsProjectScope": "Install",
"firstName": "John",
"lastName": "doe",
"email": "john.doe@gmail.com",
"phone": "5403216765",
"state": "CA",
"address": "1234 st",
"homePhoneConsentLanguage": "Fake example I consent to receiving calls etc."
}

Required Fields

All field names and values are case sensitive, so copy and paste them directly from the specs

  • pingToken : the unique pingToken value returned in the PING API response. This can be set up one of two ways.
    • Custom Variable - when on the PING step if you use the Response Parser tool you can select the pingToken value and set it to a custom variable that can be called in the POST body.

    • You can use the {{lp_ping_response:KEY}} shortcode, and replace KEY with pingToken.
  • tagID : use Test tagID '204670250' during testing, Production tagID once live)
  • service : choose the correct service value from the list of COMMON SERVICES
  • postalCode : lead zip code, default campaign field is {{zip_code}}
  • buyTimeFrame : map to your timeframe campaign field, or hardcode a default value from this list - Immediately, 1-6 months, Don't know
  • ownHome : Yes or No . If not the owner, but is authorized to make improvements, use Yes
  • partnerSourceId : Value to identify campaigns by marketing efforts or channels on the publisher side. Helps Modernize track and report quality back to publisher
  • trustedFormToken : TrustedForm Cert URL. Your PING and POST must contain at least a TrusteForm Cert URL or a Jornaya LeadiD. It's suggested to collect and send both if possible.
  • leadIDToken : Jornaya LeadiD. Your PING and POST must contain at least a TrusteForm Cert URL or a Jornaya LeadiD. It's suggested to collect and send both if possible.
  • publisherSubId : Your own internal tracking ID. For a unique value for each lead you can use the system field {{lp_lead_id}}
  • firstName : First name, default campaign field is {{first_name}}
  • lastName : Last name, default campaign field is {{last_name}}
  • email : Email address, default campaign field is {{email}}
  • phone : Phone number in plain 10 digit format , default campaign field is {{phone}}
  • state : State, default campaign field is {{state}}
  • address : Address, default campaign field is {{address}}
  • homePhoneConsentLanguage : TCPA text collected on final submit, default campaign field is {{tcpa_text}}

POST Response Mapping

The POST Response Mapping for Modernize v3 will consist of 2 different settings - the Accepted Response Mapping and the Duplicate Response Mapping

Success:

Condition: key equal with

Key: status

Value: success

Duplicate:

Condition: response contains

Key: *

Value: duplicate

The duplicate response for Modernize v3 may change and we'll update when it's confirmed.

Hit Save.

Testing + Test Parameters

Once your set up is done you'll want to run some tests.

Before you begin testing confirm you are using the staging URLs as well as the test parameters provided by Modernize:

Staging / Testing URLs

Test Parameters

  • tagID: 204670250
  • zip_code: 92604

If for some reason reason you are unable to get a test using those test parameters reach out to your rep and see if they can provide more insight.

Going Live

After you have gotten a successful test and got confirmation from Modernize you need to make 3 final changes - update the PING URL and POST URL to the production values, and update your tagID in both the PING and POST payloads to the live productino values that Modernize provides.

  1. Production PING URL: https://form-service-hs.qnst.com/ping-post/pings
  2. Production POST URL: https://form-service-hs.qnst.com/ping-post/posts
  3. Production tagID Value: provided by Modernize

That should be it - you should be all set with your buyer set up on the Modernize v3 API. Setting up a Modernize Ping Post buyer is a straightforward process once you know which fields are required and where to find them in the specs. As soon as you validate that everything is working properly in the staging environment, you can switch to production and begin delivering leads in real time. If you ever run into questions or want a second set of eyes on your setup, our team is always here to help. Reach out through the Support button in your Lead Prosper account or email us at support@leadprosper.io so we can make sure your campaign is ready to perform from day one.

Still need help? Contact Us Contact Us