Ping post instructions

  • Updated on

Ping Post posting type provides a real-time bidding process between publishers and PX. Publishers send to PX partial lead information without contact data, which gives the opportunity to dynamically price the leads according to internal statistics or real-time responses received from buyers.

Visit api.px.com for vertical specifications for all cobinations of posting types and sales models.

General PX lead processing in ping post

The basic scenario of ping post lead posting process includes the following steps:

1. Publisher sends the ping request to PX with the lead that includes all vertical-specific information, with no contact data that would allow PX to determine exact person before buying the lead (first and last names, address, phone numbers, emails, etc.).

However, ZIP code and IP Address are required in a publisher's ping request.

2. PX determines the bid (price for the lead) based on the information provided.

3. PX sends ping response to the publisher with the bid amount and Transaction ID included.

4. If the publisher is satisfied with the bid, they send the post request with the full lead info including contact data and ping identifier (Transaction ID received from PX)

5. If the lead was sold, PX sends the post response with the payout amount for the lead and corresponding Transaction ID.

6. If any error occurs on ping or post stages, PX will respond to the publisher with Transaction ID and the corresponding error (e.g. Unable to monetize). 

To prevent situations when publishers change vertical-specific data on post, system ignores all fields changed on post and lead is processed with data received on ping (except for Transactiond ID that is sent only on post). 

As for contact data, most of the fields are required only on post. However, in cases when the publisher sends all contact fields on ping as well, the lead is processed in the following way:

  • fields taken from ping:
    • City
    • State
    • ZIP code
    • IP address
  • fields taken from post:
    • FirstName
    • LastName
    • Address
    • Email Address
    • PhoneNumber
    • DayPhoneNumber 

Ping API Description

In general Ping and Post APIs uses the same methods of message delivery into PX: lead data should be provided in a body of the HTTP POST request, the lead structure should fully match PX vertical specs, etc.

<LeadData Target="Lead.Ping" Partner="xxx" Password="ppp" RequestTime="YYYY-mm-dd HH:MM:SS" UserAgent="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36" OriginalURL="http://www.exampleURL.com" SessionLength="7" TCPAText="tcpa">
  • Target="Lead.Ping" attribute should be used to submit lead as a ping request.
  • Partner attribute must contain publisher login or API token. If API token is used, the password attribute should be empty or omitted.

API partner token is used instead of login and password in cases when API publishers post leads to PX in HTTP format. For this purpose, partner token must be generated in publisher settings in advance.

If Partner login and password or API token are not correct, PX will respond with the error message:

<Response>
   <Result Value="BaeNOK">
      <Error>
         <Reason>Partner login Failed, API access denied.</Reason>
            <Param/>
            <ExtraInfo>No Valid credentials supplied.</ExtraInfo>
      </Error>
   </Result>

The main difference in lead structure for the Ping is that ContactData section can have only ZipCode and IPAddress mentioned. All other fields can be empty or omitted.

Valid ConatactData part of the lead can have one of the following formats:

  • Partial info in ContactData provided:
<ContactData>
<State>NY</State> 
<ZIPCode>10014</ZIPCode>
<IPAddress>255.255.255.255</IPAddress>
</ContactData>
  • Empty fields in ContactData for missing information:
<ContactData>
      <FirstName/>
      <LastName/>
      <Address/>
      <City/>
      <State/>
      <ZIPCode>10014</ZIPCode>
      <EmailAddress>testlead@px.com</EmailAddress>
      <PhoneNumber>6467171795</PhoneNumber>
      <DayPhoneNumber>6467171795</DayPhoneNumber>
      <IPAddress>255.255.255.255</IPAddress>
</ContactData>

QuoteData should fully correspond to PX vertical specs, i.e. with at least all mandatory fields provided. If QuoteData doesn’t match with the corresponding vertical specs, PX will respond with error message describing what is missing in lead. In case of errors the TransactionId will be mentioned as an extra parameter in the last error like in an example below:

<Response>
   <Result Value="BaeNOK">
      <Error>
         <Reason>Mandatory parameter is missing.</Reason>
         <Param>PropertyUsage</Param>
         <ExtraInfo>Section=Home, Param=PropertyUsage.</ExtraInfo>
      </Error>
      <Error>
         <Reason>Unable to monetize.</Reason>
         <Param/>
         <ExtraInfo>Param=TransactionID, Value=3A015A43-CD25-4EF5-BD82-5C19C1F40408.</ExtraInfo>
      </Error>
   </Result>
</Response>

XML example of Lead.Ping response on success:

<Response>
   <Result Value="BaeOK">
      <TransactionId>3A015A43-CD25-4EF5-BD82-5C19C1F40408</TransactionId>
      <Payout>1.25</ Payout >
   </Result>
</Response

Post API description

In general, post request specification is fully similar to Direct Post posting type, including full contact data and quote data according to vertical specs. The structure and accuracy of the lead is fully verified according to specification on the post and will be rejected in case of error.

Specific changes for the post request (HTTP):

<LeadData Target="Lead.Post" Partner="xxx" Password="ppp" TransactionId="3A015A43-CD25-4EF5-BD82-5C19C1F40408" RequestTime="YYYY-mm-dd HH:MM:SS" UserAgent="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36" OriginalURL="http://www.exampleURL.com" SessionLength="7" TCPAText="tcpa">
  • Target="Lead.Post" attribute should be used to submit lead as a Ping message.
  • Partner and Password have the same rules as on the Ping.
  • TransactionId should include the value received from PX on success response.

If PX processed the lead successfully and sold it to the buyer(s), the post response will have the format similar to ping response with an actual bid for the lead:

<Response>
   <Result Value="BaeOK">
      <TransactionId>3A015A43-CD25-4EF5-BD82-5C19C1F40408</TransactionId>
      <Payout>1.25</ Payout >
   </Result>
</Response>

In case of any errors or if the lead wasn't sold to any buyer, PX will send post response with the error message describing the reason:

<Response>
   <Result Value="BaeNOK">
      <Error>
         <Reason>Mandatory parameter is missing.</Reason>
         <Param>PropertyUsage</Param>
         <ExtraInfo>Section=Home, Param=PropertyUsage.</ExtraInfo>
      </Error>
      <Error>
         <Reason>Unable to monetize.</Reason>
         <Param/>
         <ExtraInfo>Param=TransactionID, Value=3A015A43-CD25-4EF5-BD82-5C19C1F40408.</ExtraInfo>
      </Error>
   </Result>
</Response>

Related articles

0 comments

Please sign in to leave a comment.

Related articles