Exclusive PingPost Specification |
Shared PingPost Specification
Demo operates on a directpost or pingpost system for life insurance leads.
You send your Lead data,HTTP, XML or JSON formatted, in the body of an HTTP POST request.
The XML consists of 4 sections of interest:
- LeadData: general parameters needed to communicate with the API.
- AffiliateData: describes you, your sources and the way you want the API to respond.
- ContactData: information regarding the requester.
- QuoteRequest: holding information specific to the requested product.
Fixed pricing and
Minimum required pricing are supported. These need to be discussed with our account manager.
Format
<LeadData Target="Lead.Insert" 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" TransactionId="3A015A43-CD25-4EF5-BD82-5C19C1F40408" TCPAText="tcpa">
You receive the following parameters from our account manager:
Target is the way you want to post us your lead.
Lead.Insert means inserting the lead as a direct post
Lead.Ping means ping us the lead (and a lot of contact data isn't mandatory then)
Lead.Post means post us the lead (after sending us a ping first) and then the transactionId field is mantory. The transactionId you receive from us with the ping response.
RequestTime equals the time the request was issued (Format "YYYY-mm-dd HH:MM:SS")
Remark: all dates in the XML request are in this format.
UserAgent is a string that identifies the user's internet browser or other tools from which the lead was sent, this field is not mandatory.
OriginalURL is the URL of the original source, this field is not mandatory.
SessionLength is how long a user spent on a form before submitting (in seconds), this field is not mandatory
TransactionId Can be the TransactionId of your tracking system or when working with us via ping/post tree it is the transactionId you receive from us on the ping and then this field is mandatory when posting a lead afer a ping transaction.
TCPA is the compliancy text a user must agree to according to the Telephone Consumer Protection Act before submitting. For instance: "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". TCPA field is not mandatory.
Format
<AffiliateData Id="<YourAffiliateId>" OfferId="<YourOfferIdId>" SubId="<affSub>" Sub2Id="<affSub2>" Sub3Id="<affSub3>" Sub4Id="<affSub4>" Sub5Id="<affSub5>" Source="zzz" VerifyAddress="false" RespondOnNoSale="true" SellResponseURL="YourURL" LeadId="" TrustedForm="" ClickConsentID="" PageId="" />
You receive the following parameters from our account manager:
The following parameters need to be discussed with our account manager:
LeadId is not mandatory and can be omitted or left empty when not used.
TrustedForm is not mandatory and can be omitted or left empty when not used.
ClickConsentId is not mandatory and can be omitted or left empty when not used.
pageId is not mandatory and can be omitted or left empty when not used.
VerifyAddress (Not mandatory, default = False)
When VerifyAddress is True, any verification errors that occur during Address verification will be passed back to you and the LeadInsert will NOT succeed.
The API will remember the Address data of your request, so when the Lead is reissued to the API, updated parts will be merged with the intial data and
processing continues without further address verification. If no other errors are encountered, the Lead will now pass.
This functionality creates the possibility for your users to edit input errors. The following verification errors could be returned:
- Address information provided is incomplete or invalid
- Address information is incomplete: please add unit or apt number
- Phone number provided is invalid
- Phone number provided seems to be invalid
- Contact information provided is invalid
Should multiple errors be encountered, they will be reported separated by a '|' character.
E.G. Address information provided is incomplete or invalid|Phone number provided seems to be invalid
RespondOnNoSale (Not mandatory, default = True)
When this is set to False, the API will NOT perform a callback to your SellResponseURL in case we could not sell the LEAD.
In case we could sell the Lead we will always perform a callback on your SellResponseURL (unless your SellResponseURL is not specified).
SellResponseURL (aka Post back url / S2S pixel) (Not mandatory, default = "")
If not empty, this is the URL, that you specify, that will be called by the API to inform you about the final results of the posted Lead.
We can provide information in the callback regarding TransactionID, Payout, Result, Reason and Sub2ID.
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}
The reason will only be filled in case of a NoSale and can be one of the following:
- Duplicate
- Contact information invalid
- Unable to monetize
example NoSale standard:
http://{yourserver/yourscript}?TransactionId=5B5E55EF-5D8F-4955-8C75-D1DB4EE4FA48&Payout=0.00&Result=NotSold&Reason=Unable to monetize&Sub2ID=x11d
example Sale standard:
http://{yourserver/yourscript}?TransactionId=5B5E55EF-5D8F-4955-8C75-D1DB4EE4FA48&Payout=12.50&Result=Sold&Sub2ID=x11d
example NoSale with variables (SellResponseURL="http://Server1/SellResp?T={transactionid}&Money={payout}&Err={Reason}&"):
http://Server1/SellResp?T=5B5E55EF-5D8F-4955-8C75-D1DB4EE4FA48&Money=0.00&Err=Unable to monetize&
example Sale with variables (SellResponseURL="http://Server1/SellResp?T={transactionid}&Money={payout}&Err={Reason}&"):
http://Server1/SellResp?T=5B5E55EF-5D8F-4955-8C75-D1DB4EE4FA48&Money=12.50&Err=&
Please see the example below for the specifics. All clickable values refer to a list of values that you must choose from.
Pass Back is a general mechanism supported by PX to return specific Buyer responses on successful Post to the form.
For now, it is Redirect URL and Buyer Raw Response, but it can be any other value (Buyer Email, Buyer Phone, Unique discount code, etc.) in the future.
<QuoteRequest QuoteType="life" PassBack="True">
With adding the Passback="True" to the QuoteRequest you will enable the "Passback" functionality of PX.
More information about how to use this you can find .
An example with a vertical definition can by found here.
Selected Buyers is a general mechanism supported by PX to return specific Buyers that are interested in buying the lead.
<QuoteRequest QuoteType="life" QuoteFlow="SelectedBuyers">
With adding the QuoteFlow="SelectedBuyers" to the QuoteRequest you will enable this functionality of PX.
- Send in your lead with QuoteFlow="SelectedBuyers"
PX will respond with a list of Buyers that are willing in buying this lead.
- Send in the whole lead again but this time include the Buyers you want to send this lead to and PX will only offer the lead to the buyers in this list.
It is possible to skip STEP 1 and directly send PX the buyer list.
An example with a vertical definition can be found
here.
URL: http://api.pxdemo.px.com/px
- You send us a lead XML post
- You parse the directpost response
- You create a web page that can handle our sell response
Please also see our knowledge base for Ping Post Instructions
URL: http://api.pxdemo.px.com/px
- You send us a XML/JSON Ping Request
- You send us a XML/JSON Post Request
<
?xml version="1.0" encoding="utf-8"?>
<
LeadData Target="Lead.Ping" Partner="PUB_LOGIN_HERE" Password="PUB_PASSWORD_HERE" RequestTime="2012-12-31 14:58:36" UserAgent="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36" OriginalURL="YOUR_URL_HERE" SessionLength="7" TCPAText="TCPA_TEXT_HERE" >
<
!-- Your own AffiliateData all values are mandatory except the last 3--> <
!-- LeadId can be empty or omitted when not used -->
<
AffiliateData Id="PUB_ID_HERE</FirstName> <!-- mandatory -->
<LastName>Doe</LastName> <!-- mandatory -->
<Address>1 Little West 12th</Address> <!-- mandatory -->
<City>New York</City> <!-- mandatory -->
<State>NY</State> <!-- mandatory -->
<ZIPCode>10014</ZIPCode> <!-- mandatory -->
<EmailAddress>testlead@somedomain.com</EmailAddress> <!-- mandatory -->
<PhoneNumber>6467171795</PhoneNumber> <!-- mandatory -->
<DayPhoneNumber>6467171795</DayPhoneNumber> <!-- not mandatory -->
<IPAddress>255.255.255.255</IPAddress> <!-- mandatory -->
<ResidenceType>Dorm / Student housing</ResidenceType> <!-- mandatory -->
<YearsAtResidence>1</YearsAtResidence> <!-- not mandatory, defaulted to 1 -->
<MonthsAtResidence>4</MonthsAtResidence> <!-- mandatory -->
</ContactData>
<QuoteRequest QuoteType="Life">
<Persons>
<Person>
<BirthDate>(BirthDate)</BirthDate>
<Gender>(Gender)</Gender>
</Person>
</Persons>
<CustomField1>Free text</CustomField1><!-- not mandatory max length 512-->
<CustomField2>Free text</CustomField2><!-- not mandatory max length 512-->
<CustomField3>Free text</CustomField3><!-- not mandatory max length 512-->
<CustomField4>Free text</CustomField4><!-- not mandatory max length 512-->
<CustomField5>Free text</CustomField5><!-- not mandatory max length 512-->
<CustomField6>Free text</CustomField6><!-- not mandatory max length 512-->
<CustomField7>Free text</CustomField7><!-- not mandatory max length 512-->
<CustomField8>Free text</CustomField8><!-- not mandatory max length 512-->
<CustomField9>Free text</CustomField9><!-- not mandatory max length 512-->
<CustomField10>Free text</CustomField10><!-- not mandatory max length 512-->
<CustomField11>Free text</CustomField11><!-- not mandatory max length 512-->
<CustomField12>Free text</CustomField12><!-- not mandatory max length 512-->
<CustomField13>Free text</CustomField13><!-- not mandatory max length 512-->
<CustomField14>Free text</CustomField14><!-- not mandatory max length 512-->
<CustomField15>Free text</CustomField15><!-- not mandatory max length 512-->
<Insurance>
<CurrentPolicy>
<InsuranceCompany>Allstate</InsuranceCompany> <!-- not mandatory, but defaulted to Currently not insured -->
</CurrentPolicy>
<RequestedPolicy>
<CoverageType>Term</CoverageType> <!-- mandatory -->
<CoverageTerm>5 years</CoverageTerm> <!-- mandatory -->
<CoverageAmount>25,000</CoverageAmount> <!-- mandatory -->
</RequestedPolicy>
</Insurance>
</QuoteRequest>
</LeadData>
Please remember for a post (Target="Lead.Post") to change the following:
- <LeadData >
- And add the attribute transactionId to the leaddata node: <LeadData >
<?xml version="1.0" encoding="utf-8"?>
<LeadData Target="Lead.Insert" Partner="PUB_LOGIN_HERE" Password="PUB_PASSWORD_HERE" RequestTime="2012-12-31 14:58:36" UserAgent="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36" OriginalURL="YOUR_URL_HERE" SessionLength="7" TCPAText="TCPA_TEXT_HERE" >
<!-- Your own AffiliateData all values are mandatory except the last 3--> <!-- LeadId can be empty or omitted when not used -->
<AffiliateData Id="PUB_ID_HERE</FirstName> <!-- mandatory -->
<LastName>Doe</LastName> <!-- mandatory -->
<Address>1 Little West 12th</Address> <!-- mandatory -->
<City>New York</City> <!-- mandatory -->
<State>NY</State> <!-- mandatory -->
<ZIPCode>10014</ZIPCode> <!-- mandatory -->
<EmailAddress>testlead@somedomain.com</EmailAddress> <!-- mandatory -->
<PhoneNumber>6467171795</PhoneNumber> <!-- mandatory -->
<DayPhoneNumber>6467171795</DayPhoneNumber> <!-- not mandatory -->
<IPAddress>255.255.255.255</IPAddress> <!-- mandatory -->
<ResidenceType>Dorm / Student housing</ResidenceType> <!-- mandatory -->
<YearsAtResidence>1</YearsAtResidence> <!-- not mandatory, defaulted to 1 -->
<MonthsAtResidence>4</MonthsAtResidence> <!-- mandatory -->
</ContactData>
<QuoteRequest QuoteType="Life">
<Persons>
<Person>
<Id>1</Id>
<BirthDate>1980-09-09</BirthDate> <!-- mandatory -->
<MaritalStatus>Divorced</MaritalStatus> <!-- mandatory -->
<RelationshipToApplicant>Self</RelationshipToApplicant> <!-- mandatory -->
<CreditRating>Excellent</CreditRating> <!-- mandatory -->
<Gender>Male</Gender> <!-- Male / Female -->
<DeniedInsurance>No</DeniedInsurance> <!-- mandatory -->
<Height_FT>5</Height_FT> <!-- Height feet Range(1,9) --> <!-- mandatory -->
<Height_Inch>9</Height_Inch> <!-- height inches Range(0,11) --> <!-- mandatory -->
<Weight>165</Weight> <!-- weight in pounds Range(2,300) --> <!-- mandatory -->
<Occupation>Employeed</Occupation> <!-- mandatory -->
<Education>Bachelors Degree</Education> <!-- mandatory -->
<Medication>No</Medication> <!-- mandatory -->
<Children>None</Children> <!-- mandatory -->
<LifeStyle>
<LicenseEverSuspendedRevoked>Yes</LicenseEverSuspendedRevoked> <!-- mandatory -->
<HazardousActivities>No</HazardousActivities> <!-- mandatory -->
<DUI>No</DUI> <!-- mandatory -->
</LifeStyle>
<PreExistingConditions>None</PreExistingConditions> <!-- mandatory -->
<Conditions>
<HighCholesterol>No</HighCholesterol> <!-- mandatory -->
<Ulcers>No</Ulcers> <!-- mandatory -->
<VascularDisease>No</VascularDisease> <!-- mandatory -->
<AIDSHIV>No</AIDSHIV> <!-- mandatory -->
<Arthritis>No</Arthritis> <!-- mandatory -->
<Asthma>No</Asthma> <!-- mandatory -->
<Cancer>No</Cancer> <!-- mandatory -->
<Depression>No</Depression> <!-- mandatory -->
<Diabetes>No</Diabetes> <!-- mandatory -->
<HeartDisease>No</HeartDisease> <!-- mandatory -->
<Hepatitis>No</Hepatitis> <!-- mandatory -->
<HighBloodPressure>No</HighBloodPressure> <!-- mandatory -->
<MentalIllness>No</MentalIllness> <!-- mandatory -->
<Stroke>No</Stroke> <!-- mandatory -->
<Other>No</Other> <!-- not mandatory, defaulted to No -->
</Conditions>
<MedicalHistory>
<FamilyHistoryHeartDisease>No</FamilyHistoryHeartDisease> <!-- mandatory -->
<FamilyHistoryCancer>No</FamilyHistoryCancer> <!-- mandatory -->
<Hospitalized>No</Hospitalized> <!-- mandatory -->
<Smoker>Yes</Smoker> <!-- mandatory -->
<Comment>x</Comment><!-- not mandatory -->
</MedicalHistory>
</Person>
</Persons>
<CustomField1>Free text</CustomField1><!-- not mandatory max length 512-->
<CustomField2>Free text</CustomField2><!-- not mandatory max length 512-->
<CustomField3>Free text</CustomField3><!-- not mandatory max length 512-->
<CustomField4>Free text</CustomField4><!-- not mandatory max length 512-->
<CustomField5>Free text</CustomField5><!-- not mandatory max length 512-->
<CustomField6>Free text</CustomField6><!-- not mandatory max length 512-->
<CustomField7>Free text</CustomField7><!-- not mandatory max length 512-->
<CustomField8>Free text</CustomField8><!-- not mandatory max length 512-->
<CustomField9>Free text</CustomField9><!-- not mandatory max length 512-->
<CustomField10>Free text</CustomField10><!-- not mandatory max length 512-->
<CustomField11>Free text</CustomField11><!-- not mandatory max length 512-->
<CustomField12>Free text</CustomField12><!-- not mandatory max length 512-->
<CustomField13>Free text</CustomField13><!-- not mandatory max length 512-->
<CustomField14>Free text</CustomField14><!-- not mandatory max length 512-->
<CustomField15>Free text</CustomField15><!-- not mandatory max length 512-->
<Insurance>
<CurrentPolicy>
<InsuranceCompany>Allstate</InsuranceCompany> <!-- not mandatory, but defaulted to Currently not insured -->
</CurrentPolicy>
<RequestedPolicy>
<CoverageType>Term</CoverageType> <!-- mandatory -->
<CoverageTerm>5 years</CoverageTerm> <!-- mandatory -->
<CoverageAmount>25,000</CoverageAmount> <!-- mandatory -->
</RequestedPolicy>
</Insurance>
</QuoteRequest>
</LeadData>
{
"type": "jsonwsp/request",
"version": "1.0",
"methodname": "Lead.Ping",
"LeadData": {
"Target": "Lead.Ping",
"Partner": "PUB_LOGIN_HERE",
"Password": "PUB_PASSWORD_HERE",
"RequestTime": "2012-12-31 14:58:36",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36",
"OriginalURL": "YOUR_URL_HERE",
"SessionLength": "7",
"TCPAText": "TCPA_TEXT_HERE",
"AffiliateData": {
"Id": "PUB_ID_HERE
Doe
1 Little West 12th
New York
NY
10014
testlead@somedomain.com
6467171795
6467171795
255.255.255.255
}
}
}
Please remember for a post ("Target" : "Lead.Post",) to change the following:
- And add transactionId
{
"type": "jsonwsp/request",
"version": "1.0",
"methodname": "Lead.Insert",
"LeadData": {
"Target": "Lead.Insert",
"Partner": "PUB_LOGIN_HERE",
"Password": "PUB_PASSWORD_HERE",
"RequestTime": "2012-12-31 14:58:36",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36",
"OriginalURL": "YOUR_URL_HERE",
"SessionLength": "7",
"TCPAText": "TCPA_TEXT_HERE",
"AffiliateData": {
"Id": "PUB_ID_HERE
Doe
1 Little West 12th
New York
NY
10014
testlead@somedomain.com
6467171795
6467171795
255.255.255.255
}
}
}
Command=HTTPPost&Target=Lead.Insert&PartnerToken=xxxxx&RequestTime=2012-12-31 14:58:36&UserAgent=Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36&
OriginalURL=YOUR_URL_HERE&SessionLength=7&TCPAText=TCPA_TEXT_HERE&AffiliateData.Id=PUB_ID_HERE Doe 1 Little West 12th New York NY 10014 testlead@somedomain.com 6467171795 6467171795 255.255.255.255
AffiliateData.#ResidenceType" class=valueLink
back
No
Yes
back
No
Yes
back
No
Yes
back
No
Yes
back
None
1
2
3
4
5
5+
back
No
Yes
back
5 years
10 years
15 years
20 years
25 years
30 years
Not sure
back
Excellent
Good
Some Problems
Major Problems
back
Employeed
Government
Homemaker
Retired
Student Living w/ Parents
Student not Living w/ Parents
Unemployed
Military
Retail
Sales
Marketing
IT
Medical
Unknown
BusinessOwner
Student
SalesInside
SalesOutside
Scientist
OtherTechnical
MilitaryEnlisted
Architect
Other
back
No
Yes
back
No
Yes
back
No
Yes
back
No
Yes
back
Bachelors Degree
Doctorate Degree
High school diploma
Masters Degree
Other
None
Some College
Associate Degree
back
No
Yes
back
No
Yes
back
Yes
No
back
No
Yes
back
No
Yes
back
No
Yes
back
No
Yes
back
No
Yes
back
No
Yes
back
25,000
50,000
75,000
100,000
200,000
500,000
1,000,000
5,000,000
back
Allstate
American General
Aviva
Banner Life
Fidelity Life
Genworth Financial
Great West Life
Hartford Life
ING
John Hancock
Legal & General
Lincoln National
Massachusetts Mutual (Mass Mutual)
MetLife
Mutual of Omaha
New York Life
Northwestern Mutual
Pacific Life
Prudential
Transamerica
Company not listed
Currently not insured
back
Term
Whole Life
Universal
Not Sure
back
Divorced
Married
Separated
Single
Widowed
back
No
Yes
back
No
Yes
back
None
Yes
back
Self
Spouse
Child
Sibling
Parent
Grandparent
Grandchild
Other
back
Dorm / Student housing
I am renting
My own house
Other
With my parents
back
1
2
3
4
5
6
7
8
9
10
15
20
25
30
back
No
Yes
back
Yes
No
back
No
Yes
back
No
Yes
back
AL (Alabama)
AK (Alaska)
AZ (Arizona)
AR (Arkansas)
CA (California)
CO (Colorado)
CT (Connecticut)
DE (Delaware)
DC (District of Columbia)
FL (Florida)
GA (Georgia)
HI (Hawaii)
ID (Idaho)
IL (Illinois)
IN (Indiana)
IA (Iowa)
KS (Kansas)
KY (Kentucky)
LA (Louisiana)
ME (Maine)
MD (Maryland)
MA (Massachusetts)
MI (Michigan)
MN (Minnesota)
MS (Mississippi)
MO (Missouri)
MT (Montana)
NE (Nebraska)
NV (Nevada)
NH (New Hampshire)
NJ (New Jersey)
NM (New Mexico)
NY (New York)
NC (North Carolina)
ND (North Dakota)
OH (Ohio)
OK (Oklahoma)
OR (Oregon)
PA (Pennsylvania)
RI (Rhode Island)
SC (South Carolina)
SD (South Dakota)
TN (Tennessee)
TX (Texas)
UT (Utah)
VT (Vermont)
VA (Virginia)
WA (Washington)
WV (West Virginia)
WI (Wisconsin)
WY (Wyoming)
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Result Value="BaeOK">
<TransactionId>3A015A43-CD25-4EF5-BD82-5C19C1F40408</TransactionId>
</Result>
</Response>
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Result Value="BaeNOK">
<Error>
<Reason>Invalid PhoneNumber.</Reason>
<Param>PhoneNumber</Param>
<ExtraInfo>Param=PhoneNumber, Value=333795, Error=Number bad format.</ExtraInfo>
</Error>
</Result>
</Response>
{
"Result":"BaeOK",
"TransactionId":"8DF593E1-66CC-4F6C-B4FE-471108C86FAC"
}
{
"Result":"BaeNOK",
"Reason":"Parameter value does not pass check.",
"Param":"PhoneNumber",
"ExtraInfo":"Param=PhoneNumber, Value=333795, Check=USPhone."
}
- Partner login Failed, API access denied.
- Invalid EmailAddress.
- Value does not pass the check.
You will receive information which values aren't correct.
- Mandatory parameter is missing.
You will receive information which parameters are missing.
- Invalid or missing parameter value.You will receive information which parameters are missing.
back
We do an HTTP GET Request to a URL on your server.
?TransactionId=D9562D0D-950F-4F86-B102-A225E8D2E2A3&Payout=10.54&Result=Sold
?TransactionId=D9562D0D-950F-4F86-B102-A225E8D2E2A3&Payout=0.00&Result=NotSold