Match Ping Leads

API 2.0 Specifications for Brand Consent

Introduction

MatchPing is a new request type that happens before the lead submission and allows us to obtain a list of potentially eligible brands and their indicative bids.

It is similar to Ping or CallPing:

  • MatchPing should contain as much lead data as possible
  • Lead data is then analyzed by PX and run against potential buyers’ filters in order to find the best-matching buyers
  • As an output, PX provides the list of unique Brands, any available supplemental brand info, and an indicative bid for each brand
  • Publisher can show the Brands to the lead on his branded page, collect consent, and send it as a part of the lead data to PX
   

Publisher setup

Match Ping integration could be done under an existing publisher account if its type is one of the following:

  • Direct Post
  • Branded
  • Common
 

Posting URL

Match Ping URL: https://leadapi.px.com/api/lead/matchping

Header Fields Table

Key Required Value
Content-Type Yes Application/json for JSON requests
Application/xml for XML requests
Accept No Application/json for JSON response
Application/xml for XML response

Examples

Lead data structure is defined by Vertical integration and should maintain the same structure, though number of required fields is significantly lower.

Minimal configuration of Match Ping request is shown below:



{
    "ApiToken": "apitoken",
    "Vertical": "vertical",
    "OriginalUrl": "URL", 
    "Source": "source", 
    "JornayaLeadId": "jornayaid", 
    "SessionLength": "38", 
    "VerifyAddress": "false", 
    "ContactData": { "ZipCode": "zip"} 
}

However, it is strongly encouraged to send in as much lead data as possible in order to get more precise results. While selecting potential brands, the most important step is running lead data across campaign filters – so the more information is analysed, the higher the conversion rates are.

Fields Table

Parameter Required Ping Accepted Values
 Description (data type)
ApiToken Yes Provided by PX GUID format
Vertical Yes Provided at start String
OriginalURL Yes URL where the lead is from String
Source Yes String
JornayaLeadId Yes, for some verticals Jornaya LeadId (GUID format) See link on how to implement on form
SessionLength Yes Amount of time spent by the user to fill out the form in seconds String
VerifyAddress Yes false String
ZipCode Yes 5 digit zip code String

Success – Match Ping

Success response will provide a list of potential brands with brand details, indicative bids for those brands (where available) plus MatchPingID.
MatchPingID must then be returned by the publisher along with the Lead data submit in the BrandConsent section in order for PX to know which MatchPing belongs to which lead.


{ 
  "TransactionId": "809674f5-9ba9-4945-ae99-e62315c908f5", 
  "MatchPingId": "809674f5-9ba9-4945-ae99-e62315c908f5", 
  "Success": true, 
  "Payout": null, 
  "Message": null, 
  "Errors": null, 
  "Sold": null, 
  "RedirectUrl": null, 
  "BuyerRawResponse": null, 
  "BuyerGuid": null, 
  "Environment": "Testing", 
  "Legs": null, 
  "Brands": [ 
    { 
      "PxId": "94aa53a4-6652-4499-9882-44de0dbbd354", 
      "Name": "Brand 1", 
      "Description": "Description of Brand 1", 
      "Uid": null, 
      "Link": "https://px.com", 
      "LogoUrl": "https://www.px.com//srv/htdocs/wp-content/uploads/2022/02/px-site-icon.png", 
      "PhoneNumber": "123456789", 
      "TCPA": "TCPA text for Brand 1", 
      "Bid": 12.34 
    }, 
    { 
      "PxId": "0311617f-9e4b-4627-9734-559a2a252c35", 
      "Name": "Brand 2", 
      "Description": "Description of Brand 2", 
      "Uid": "Brand 2 External Id", 
      "Link": "https://px.com", 
      "LogoUrl": "https://www.px.com//srv/htdocs/wp-content/uploads/2022/02/px-site-icon.png", 
      "PhoneNumber": "123456789", 
      "TCPA": "TCPA text for Brand 2", 
      "Bid": 23.45 
    } 
  ] 
}




<?xml version="1.0" encoding="UTF-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
  <TransactionId>0b156a37-fe10-48c2-b38f-7e7b59497e7a</TransactionId> 
  <MatchPingId>0b156a37-fe10-48c2-b38f-7e7b59497e7a</MatchPingId> 
  <Success>true</Success> 
  <Payout xsi:nil="true" /> 
  <Sold xsi:nil="true" /> 
  <BuyerGuid xsi:nil="true" /> 
  <Environment>Testing</Environment> 
  <Brands> 
    <BrandMatch> 
      <PxId>e4759b65-d688-4af4-9651-1949e6bd5cde</PxId> 
      <Name>Brand 1</Name> 
      <Description>Description of Brand 1</Description> 
      <Link>https://px.com</Link> 
      <LogoUrl>https://www.px.com//srv/htdocs/wp-content/uploads/2022/02/px-site-icon.png</LogoUrl> 
      <PhoneNumber>123456789</PhoneNumber> 
      <TCPA>TCPA text for Brand 1</TCPA> 
      <Bid>12.34</Bid> 
    </BrandMatch> 
    <BrandMatch> 
      <PxId>0c9b2083-63ed-44fb-a677-626460c70184</PxId> 
      <Name>Brand 2</Name> 
      <Description>Description of Brand 2</Description> 
      <Uid>Brand 2 External Id</Uid> 
      <Link>https://px.com</Link> 
      <LogoUrl>https://www.px.com//srv/htdocs/wp-content/uploads/2022/02/px-site-icon.png</LogoUrl> 
      <PhoneNumber>123456789</PhoneNumber> 
      <TCPA>TCPA text for Brand 2</TCPA> 
      <Bid>23.45</Bid> 
    </BrandMatch> 
  </Brands> 
</Result>

 

Success – Post


{
"TransactionId": "D0447C7B-452B-4F2A-9D7B-F3F72848EEE9",
"Success": true,
"Payout": 8.50,
"Message": null,
"Errors": null,
"Sold": null,
"RedirectUrl": null,
"BuyerRawResponse": null,
"Environment": "Testing",
"Legs": null
}



<?xml version="1.0" encoding="UTF-8"?>
<Result xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<TransactionId>143E2B7A-73A3-41F4-87DA-DB8E136606B0</TransactionId>
	<Success>true</Success>
	<Payout>12.34</Payout>
	<Sold xsi:nil="true" />
	<Environment>Testing</Environment>
</Result>

Failure – Match Ping

“No matched brands found” is returned to the publisher if PX couldn’t match any brands.


{
"TransactionId": "21CD8A6D-B562-4755-B893-E22B32ED398B",
"MatchPingId": null,
"Success": false,
"Payout": null,
"Message": "No matched brands found",
"Errors": [],
"Sold": null,
"RedirectUrl": null,
"BuyerRawResponse": null,
"BuyerGuid": null,
"Environment": "Production",
"Legs": null,
"Brands": null
}



<?xml version="1.0" encoding="UTF-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<TransactionId>1F7E25F3-9C11-4AA6-AD47-83BC075E8130</TransactionId>
<Success>false</Success>
<Payout xsi:nil="true" />
<Message>No matched brands found</Message>
<Errors />
<Sold xsi:nil="true" />
<BuyerGuid xsi:nil="true" />
<Environment>Production</Environment>
</Result>

 

Failure – Post

“Unable to monetize” is returned to the publisher if the lead was not accepted by the buyer in PX.


{
"TransactionId": "21CD8A6D-B562-4755-B893-E22B32ED398B",
"MatchPingId": null,
"Success": false,
"Payout": null,
"Message": "Unable to monetize",
"Errors": [],
"Sold": null,
"RedirectUrl": null,
"BuyerRawResponse": null,
"BuyerGuid": null,
"Environment": "Production",
"Legs": null,
"Brands": null
}



<?xml version="1.0" encoding="UTF-8"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<TransactionId>1F7E25F3-9C11-4AA6-AD47-83BC075E8130</TransactionId>
<Success>false</Success>
<Payout xsi:nil="true" />
<Message>Unable to monetize</Message>
<Errors />
<Sold xsi:nil="true" />
<BuyerGuid xsi:nil="true" />
<Environment>Production</Environment>
</Result>

Next steps

After Match Ping is implemented, it is required to update existing Direct Post and Ping Post integrations with “BrandConsent” section in lead data. Please follow this instructions depending on your integration type: