This document describes how to post undersold plumbing leads to PX using ping post. We accept POST requests in XML and JSON. Follow this article to read how ping post works in PX.
Posting URL
Before leads can be posted into PX’s live environment, tests need to be performed to ensure success. For testing purposes, PX will set the publisher campaign to a test mode during the integration. All the tests and responses on these tests can be found in the Test leads report.
Forcing a success: When 90100 zip code is used in the staging environment, the API will respond with success if the API is configured correctly.
Once a lead has been successfully posted and proper posting is confirmed by PX, leads can be posted to the live environment. To post into the live environment, PX will set the publisher campaign to the production mode after approving the successful test.
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
Ping<?xml version="1.0" encoding="UTF-8"?>
<Lead>
<ApiToken>xxxx;/ApiToken>
<Vertical>plumbing</Vertical>
<JornayaLeadId>0</JornayaLeadId>
<TrustedForm>0</TrustedForm>
<OriginalUrl>https://exampleurl.com</OriginalUrl>
<SessionLength>38</SessionLength>
<Source>Social</Source>
<SubId>FB1</SubId>
<Sub2Id></Sub2Id>
<Sub3Id></Sub3Id>
<Sub4Id></Sub4Id>
<Sub5Id></Sub5Id>
<UserAgent>Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36</UserAgent>
<TcpaText>By clicking Get My Quotes, I authorize plumbing companies, their dealers and partner companies to contact me about plumbing offers by phone calls and text messages to the number I provided. I authorize that these marketing communications may be delivered to me using an automatic telephone dialing system or by prerecorded message. I understand that my consent is not a condition of purchase</TcpaText>
<VerifyAddress>false</VerifyAddress>
<ContactData>
<IpAddress>255.255.255.127</IpAddress>
<State>NY</State>
<ZipCode>90100</ZipCode>
</ContactData>
<Custom>
<Field1>Free text</Field1>
<Field2>Free text</Field2>
<Field3>Free text</Field3>
<Field4>Free text</Field4>
<Field5>Free text</Field5>
<Field6>Free text</Field6>
<Field7>Free text</Field7>
<Field8>Free text</Field8>
<Field9>Free text</Field9>
<Field10>Free text</Field10>
</Custom>
<Person>
<BirthDate>1980-07-27</BirthDate>
<Gender>Male</Gender>
</Person>
<Plumbing>
<PlumbingType>Pipe</PlumbingType>
<PropertyType>Residential</PropertyType>
<OwnRented>Own</OwnRented>
<ProjectType>Repair</ProjectType>
<ProjectTiming>Timing is flexible</ProjectTiming>
</Plumbing>
<Distribution>
<Exclude>
<Directive>
<Hash>HashedLegName02</Hash>
</Directive>
</Exclude>
<Exclude>
<Directive>
<Name>LegName184</Name>
</Directive>
</Exclude>
<OpenSlots>5</OpenSlots>
</Distribution>
</Lead>Post<?xml version="1.0" encoding="UTF-8"?>
<Lead>
<ApiToken>xxxx;/ApiToken>
<Vertical>plumbing</Vertical>
<JornayaLeadId>0</JornayaLeadId>
<TrustedForm>0</TrustedForm>
<OriginalUrl>https://exampleurl.com</OriginalUrl>
<SessionLength>38</SessionLength>
<Source>Social</Source>
<SubId>FB1</SubId>
<Sub2Id></Sub2Id>
<Sub3Id></Sub3Id>
<Sub4Id></Sub4Id>
<Sub5Id></Sub5Id>
<UserAgent>Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36</UserAgent>
<TcpaText>By clicking Get My Quotes, I authorize plumbing companies, their dealers and partner companies to contact me about plumbing offers by phone calls and text messages to the number I provided. I authorize that these marketing communications may be delivered to me using an automatic telephone dialing system or by prerecorded message. I understand that my consent is not a condition of purchase</TcpaText>
<TransactionId>17D15ADF-2177-4873-9CCC-680E852CDAD4</TransactionId>
<ContactData>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<Address>1 Little West 12th</Address>
<City>New York</City>
<State>NY</State>
<ZipCode>10014</ZipCode>
<EmailAddress>test@testemail.com</EmailAddress>
<PhoneNumber>6367171795</PhoneNumber>
<DayPhoneNumber>6367171795</DayPhoneNumber>
<IpAddress>255.255.255.255</IpAddress>
</ContactData>
<Custom>
<Field1>Free text</Field1>
<Field2>Free text</Field2>
<Field3>Free text</Field3>
<Field4>Free text</Field4>
<Field5>Free text</Field5>
<Field6>Free text</Field6>
<Field7>Free text</Field7>
<Field8>Free text</Field8>
<Field9>Free text</Field9>
<Field10>Free text</Field10>
</Custom>
<Person>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<BirthDate>1980-07-27</BirthDate>
<Gender>Male</Gender>
<CreditRating>Excellent</CreditRating>
</Person>
<Plumbing>
<PlumbingType>Pipe</PlumbingType>
<PropertyType>Residential</PropertyType>
<OwnRented>Own</OwnRented>
<ProjectType>Repair</ProjectType>
<ProjectTiming>Timing is flexible</ProjectTiming>
</Plumbing>
</Lead>
{
"TransactionId": "49CE4DB7-775B-405B-BBBD-B23FB003073A",
"Success": false,
"Payout": null,
"Message": "BadRequest",
"Errors": [
"'Project Type' must not be empty.",
"'Project Type' must be one of Repair, Replace, Install. Your value is ''."
]
"Sold": null,
"RedirectUrl": null,
"BuyerRawResponse": null,
"Environment": null,
"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>49CE4DB7-775B-405B-BBBD-B23FB003073A</TransactionId>
<Success>false</Success>
<Payout xsi:nil="true" />
<Message>BadRequest</Message>
<Errors>
<string>'Project Type' must not be empty.</string>
<string>'Project Type' must be one of Repair, Replace, Install. Your value is ''.</string>
</Errors>
<Sold xsi:nil="true" />
</Result>
The responses from our API shows if a Ping/Post has been successful or not, and if the lead wasn’t successful, why the Ping/Post has been rejected.
The “Message” parameter gives a general error code.
The “Errors” parameter gives the specific cause of the error, such as an invalid or missing value for a specific field.
If the Ping/Post was unsuccessful, the Payout and Sold field will show a “Null” value.
States
AL
AK
AZ
AR
CA
CO
CT
DE
FL
GA
HI
ID
IL
IN
IA
KS
KY
LA
ME
MD
MA
MI
MN
MS
MO
MT
NE
NV
NH
NJ
NM
NY
NC
ND
OH
OK
OR
PA
RI
SC
SD
TN
TX
UT
VT
VA
WA
WV
WI
WY
PlumbingType
Drains
Faucets
Fixture
Pipe
Sprinkler systems
Septic system
Water heater
Sewer main
Gutters
Water main
Plumbing for an addition or remodel
Other
Plumbing
Implementing Jornaya LeadId
To start generating the Jornaya LeadId token on your leads from your page, a script needs to be added to your website. Follow the guidance on how to implement this script.
Implementing TrustedForm
To start generating the TrustedForm CertURL on your leads from your page, a script needs to be added to your website. Follow the guidance on how to implement this script.
Undersold
When leads are being sold to PX that have already been sold to another lead buyer, the undersold method should be used.
Add the following parameters to the request body:
OpenSlots – indicates the number of times this lead can still be sold;
Name / Hash – indicates to which buyer this lead has already been sold. These buyers won’t be taken into account in the bidding process
Lost bids
This request is initiated after the ping response is received and instructs our API what price the lead has been sold when our bid was lower. This helps us and our lead buyers to optimize the bids. Lost bids Post URL: https://secureopenapi.px.com/px
This indicates that my system needs to treat this request as a price update and not a normal lead
String
Partner
The username used to login the account, specifically the account for this campaign (Not MasterAccount)
String
Password
The password used to login the account, specifically the account for this campaign (Not MasterAccount)
AffiliateId
The publisherID provided at the start of the integration
String
Payout
The price you sold the lead for to another buyer / the price we lost the lead to
String
TransactionId
The same as you would on the post. We return a TransactionId on the ping and you return this here to match ping with the lost bid. Should you have problems retrieving our TransactionId from the response it is also possible to parse your own unique id on the ping in the TransactionId parameter.