API Specs Ping Post

Introduction

This document describes how to post calls hvac 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.

Ping URL: https://leadapi.px.com/api/call/ping

Post URL: https://leadapi.px.com/api/call/post

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.

SellResponseURL

Our API does not provide info about the lead being sold or not with Direct Post and Call & Lead (Ping Post Call) posts.

If not empty, this is the (Postback) URL, that you specify, that will be called by the API to inform you about the final results of the posted Lead. Please consult this article in our knowledge base to setup the SellResponseURL.

There are 2 ways, depending on the SellResponseURL you specify: ‘standard’ and ‘with variables’.
In ‘standard’ we defined the lay-out. In ‘with variables’ you define the layout using our variable labels enclosed in curly brackets {}.
We will only return the variables that you specify.

standard: {SellResponseURL}TransactionId={transactionid}&Payout={payout}&Result={Result}&Reason={Reason}&Sub2ID={sub2id}
with variables: {SellResponseURL}yourvar={transactionid}&yourvar={payout}&yourvar={Result}&yourvar={Reason}&yourvar={sub2id}

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>Hvac</Vertical>
   <SubId>FB1</SubId>
   <Sub2Id></Sub2Id>
   <Sub3Id></Sub3Id>
   <Sub4Id></Sub4Id>
   <Sub5Id></Sub5Id>
   <OfferId>0</OfferId>
   <UserAgent>Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36</UserAgent>
   <OriginalUrl>https://www.exampleURL.com</OriginalUrl>
   <Source>Social</Source>
   <JornayaLeadId></JornayaLeadId>
   <TrustedForm></TrustedForm>
   <SessionLength>38</SessionLength>
   <TcpaText>By clicking Get My Quotes, I authorize security companies, their dealers and partner companies to contact me about security 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>
   <ContactData>
      <State>NY</State>
      <ZipCode>901100</ZipCode>
      <IpAddress>255.255.255.255</IpAddress>
   </ContactData>
   <Person>
      <BirthDate>1980-12-09</BirthDate>
      <Gender>Male</Gender>
   </Person>
   <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>
   <Home>
      <ProjectType>New Unit Installed</ProjectType>
      <AirType>Heating</AirType>
      <AirSubType>Gas Furnace</AirSubType>
      <PropertyType>Residential</PropertyType>
      <NumberOfRooms>5</NumberOfRooms>
      <NumberOfFloors>2</NumberOfFloors>
      <Ownership>Own</Ownership>
      <AuthorizedToMakeChanges>Yes</AuthorizedToMakeChanges>
      <SystemAge>0-4 years</SystemAge>
      <SystemCondition>Not working</SystemCondition>
      <HomeAge>5</HomeAge>
      <Financing>No</Financing>
   </Home>
</Lead>
 
Post
<?xml version="1.0" encoding="UTF-8"?>
<Lead>
   <ApiToken>xxxx</ApiToken>
   <Vertical>Hvac</Vertical>
   <SubId>FB1</SubId>
   <Sub2Id></Sub2Id>
   <Sub3Id></Sub3Id>
   <Sub4Id></Sub4Id>
   <Sub5Id></Sub5Id>
   <OfferId>0</OfferId>
   <UserAgent>Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36</UserAgent>
   <OriginalUrl>https://www.exampleURL.com</OriginalUrl>
   <Source>Social</Source>
   <JornayaLeadId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</JornayaLeadId>
   <TrustedForm>https://cert.trustedform.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</TrustedForm>
   <SessionLength>38</SessionLength>
   <TcpaText>By clicking Get My Quotes, I authorize HVAC companies, their dealers and partner companies to contact me about security 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>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</TransactionId>
   <ContactData>
       <FirstName>John</FirstName>
       <LastName>Doe</LastName>
       <Address>1 Little West 12th</Address>
       <City>New York</City>
        <State>NY</State>
       <ZipCode>90110</ZipCode>
       <EmailAddress>testlead@somedomain.com</EmailAddress>
       <PhoneNumber>6543218454</PhoneNumber>
       <DayPhoneNumber>6543218454</DayPhoneNumber>
       <IpAddress>255.255.255.255</IpAddress>
   </ContactData>
   <Person>
      <FirstName>John</FirstName>
      <LastName>Doe</LastName>
      <BirthDate>1980-12-09</BirthDate>
      <Gender>Male</Gender>
   </Person>
   <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>
   <Home>
      <ProjectType>New Unit Installed</ProjectType>
      <AirType>Heating</AirType>
      <AirSubType>Gas Furnace</AirSubType>
      <PropertyType>Residential</PropertyType>
      <NumberOfRooms>5</NumberOfRooms>
      <NumberOfFloors>2</NumberOfFloors>
      <Ownership>Own</Ownership>
      <AuthorizedToMakeChanges>Yes</AuthorizedToMakeChanges>
      <SystemAge>0-4 years</SystemAge>
      <SystemCondition>Not working</SystemCondition>
      <HomeAge>5</HomeAge>
      <Financing>No</Financing>
   </Home>
</Lead>


Ping
{
    "ApiToken": "xxxx",
    "Vertical": "Hvac",
    "SubId": "FB1",
    "Sub2Id": "",
    "Sub3Id": "",
    "Sub4Id": "",
    "Sub5Id": "",
    "OfferId": "0",
    "UserAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36",
    "OriginalUrl": "https://www.exampleURL.com",
    "Source": "Social",
    "JornayaLeadId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "TrustedForm": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "SessionLength": "38",
    "TcpaText": "By clicking Get My Quotes, I authorize HVAC companies, their dealers and partner companies to contact me about security 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",
    "ContactData": {
        "State": "NY",
        "ZipCode": "90110",
        "IpAddress": "255.255.255.255"
    },
    "Person": {
        "BirthDate": "1980-12-09",
        "Gender": "Male"
    },
    "Custom": {
	"Field1": "Free text",
	"Field2": "Free text",
	"Field3": "Free text",
	"Field4": "Free text",
	"Field5": "Free text",
	"Field6": "Free text",
	"Field7": "Free text",
	"Field8": "Free text",
	"Field9": "Free text",
	"Field10": "Free text"
	},
    "Home": {
        "ProjectType": "New Unit Installed",
        "AirType": "Heating",
        "AirSubType": "Gas Furnace",
        "PropertyType": "Residential",
        "NumberOfRooms": "5",
        "NumberOfFloors": "2",
        "Ownership": "Own",
        "AuthorizedToMakeChanges": "Yes",
        "SystemAge": "0-4",
        "SystemCondition": "Not working",
        "HomeAge": "5",
        "Financing": "Not sure"
    }
}
 
Post
{
    "ApiToken": "xxxx",
    "Vertical": "Hvac",
    "SubId": "FB1",
    "Sub2Id": "",
    "Sub3Id": "",
    "Sub4Id": "",
    "Sub5Id": "",
    "OfferId": "0",
    "UserAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36",
    "OriginalUrl": "https://www.exampleURL.com",
    "Source": "Social",
    "JornayaLeadId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "TrustedForm": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "SessionLength": "38",
    "TcpaText": "By clicking Get My Quotes, I authorize HVAC companies, their dealers and partner companies to contact me about security 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",
    "TransactionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ContactData": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": "1 Little West 12th",
        "City": "New York",
        "State": "NY",
        "ZipCode": "90110",
        "EmailAddress": "testlead@somedomain.com",
        "PhoneNumber": "6543218454",
        "DayPhoneNumber": "6543218454",
        "IpAddress": "255.255.255.255"
    },
    "Person": {
        "FirstName": "John",
        "LastName": "Doe",
        "BirthDate": "1980-12-09",
        "Gender": "Male"
    },
    "Custom": {
	"Field1": "Free text",
	"Field2": "Free text",
	"Field3": "Free text",
	"Field4": "Free text",
	"Field5": "Free text",
	"Field6": "Free text",
	"Field7": "Free text",
	"Field8": "Free text",
	"Field9": "Free text",
	"Field10": "Free text"
	},
    "Home": {
        "ProjectType": "New Unit Installed",
        "AirType": "Heating",
        "AirSubType": "Gas Furnace",
        "PropertyType": "Residential",
        "NumberOfRooms": "5",
        "NumberOfFloors": "2",
        "PurchaseTimeframe": "Immediately",
        "Ownership": "Own",
        "AuthorizedToMakeChanges": "Yes",
        "SystemAge": "0-4",
        "SystemCondition": "Not working",
        "HomeAge": "5",
        "Financing": "Not sure"
    }
}

Fields Table

Parameter	Required Ping	Required Post	Accepted Values	Default to	Description (data type)
ApiToken	Yes	Yes	Provided by PX		GUID format
Vertical	Yes	Yes	HVAC		String
SubId	Yes	Yes	Format provided at start		String
Sub2Id	No	No			String
Sub3Id	No	No			String
Sub4Id	No	No			String
Sub5Id	No	No			String
OfferId	Yes	Yes			String
UserAgent	No	No			String
OriginalUrl	Yes	Yes	URL where the lead is from		String
Source	Yes	Yes	Discuss with Acc. Manager		String
JornayaLeadId	No	No	Jornaya LeadId (GUID format)		See link on how to implement on form
Trustedform	No	No	TrustedForm Cert. URL		See link on how to implement on form
SessionLength	Yes	Yes	Amount of time spent by the user to fill out the form in seconds		Integer
TcpaText	No	No	Consent language		String
TransactionId	No	Yes	Retrieve from Ping Response		GUID format
FirstName	No	Yes			String
LastName	No	Yes			String
Address	No	Yes			String
City	No	Yes			String
State	No	No	See accepted values list		String
ZipCode	No	No	5 digit zip code		String
EmailAddress	No	No	Valid email address		String
PhoneNumber	Yes	Yes	Valid 10 digit phone number without formatting 8887777777		Integer
DayPhoneNumber	No	No	Valid 10 digit phone number without formatting 8887777777		Integer
IpAddress	No	No	Example: 38.88.150.2		Integer
BirthDate	No	No	yyyy-MM-dd		String
Gender	No	No	Male / Female / Unspecified		String
Field1	No	No	Free text field		String
Field2	No	No	Free text field		String
Field3	No	No	Free text field		String
Field4	No	No	Free text field		String
Field5	No	No	Free text field		String
Field6	No	No	Free text field		String
Field7	No	No	Free text field		String
Field8	No	No	Free text field		String
Field9	No	No	Free text field		String
Field10	No	No	Free text field		String
Ownership	No	No	Own / Rented		String
AuthorizedToMakeChanges	Yes, if Ownership is Rented	Yes, if Ownership is Rented	Yes/No	Yes if Ownership = “Own”; No if “Rented”	String
ProjectType	No	No	New Unit Installed / Repair / Service / Maintenance / Cleaning / Upgrade		String
AirType	No	No	Heating / Cooling / Heating and Cooling		String
AirSubType	No	No	See accepted values list		String
PropertyType	No	No	Residential / Commercial		String
NumberOfRooms	No	No			Integer
NumberOfFloors	No	No			Integer
PurchaseTimeframe	No	No	Immediately / 1-3 months / 3-6 months / Within a Year / Not Sure		String
SystemAge	No	No	See accepted values list		String
SystemCondition	No	No	See accepted values list		String
HomeAge	No	No			Integer
Financing	No	No	Yes / No / Not sure		String

PX responds with accurate feedback on how to update your request for it to be accepted by the API.

Success – Ping


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


<?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>ce34e151-6d00-488d-a465-3fa3cebe7ff9</TransactionId>
	<Success>true</Success>
	<Payout>8.50</Payout>
	<Sold xsi:nil="true" />
	<Environment>Testing</Environment>
</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


{
    "TransactionId": "49CE4DB7-775B-405B-BBBD-B23FB003073A",
    "Success": false,
    "Payout": null,
    "Message": "BadRequest",
    "Errors": [
        
    ]
    "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>
      
   </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.

RespondOnNoSale

When this is set to False, the API will NOT perform a callback to your SellResponseURL in case we could not sell the LEAD.

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

AirSubType

Gas Furnace
Propane Furnace
Oil Furnace
Electric Furnace
Gas Boiler
Propane Boiler
Oil Boiler 1
Electric Boiler
Central Air
Heat Pump
Water Heater
Furnace
Boiler

SystemAge

0-4 years
5-8 years
9+ years
Not Sure
Unspecified

SystemCondition

Not working
Poor heating or cooling
Strange noise or vibration
Musty or unusual smell
Time to replace
Something else
Unspecified

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.

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

Code examples


Post
<?xml version="1.0" encoding="utf-8"?>
<LeadData Target="Lead.RejectWinner" Partner="{Username}" Password="{password}" AffiliateId="{PublisherID}">
    <Payout>{payout}</Payout>
    <TransactionId>{TransactionId}</TransactionId>
</LeadData>


Post
{
    "type": "jsonwsp/request", 
    "version": "1.0", 
    "methodname": "Lead.RejectWinner", 
    "LeadData":
    {
        "Target" : "Lead.RejectWinner",
        "Partner" : "{Username}",
        "Password" : "{Password}",
        "AffiliateId" : "{PublisherID}",
        "Payout" : "{Payout}",
        "TransactionId" : "{TransactionId}"
    }
}

In addition, HTTP format can be used:

Post
https://secureopenapi.px.com/px?Command=HTTPPost&Target=Lead.RejectWinner&Partner={Username}&Password={Password}&AffiliateId={PublisherID}&Payout={Payout}&TransactiondId={TransactionId}

Fields table

Parameter	Explanation	Description (data type)
Target=”Lead.RejectWinner”	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.	String

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

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

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