Ping Post – Exclusive

API 2.0 Specifications for Personal Loans

Introduction

This document describes how to post exclusive personal loans 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/lead/ping

Post URL: https://leadapi.px.com/api/lead/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.

 

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
{
    "ApiToken": "xxxx",
    "Vertical": "personalloans",
    "SubId": "FB1",
    "Sub2Id": "",
    "Sub3Id": "",
    "Sub4Id": "",
    "Sub5Id": "",
    "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": "0",
    "TrustedForm": "0",
    "SessionLength": "38",
    "TcpaText": "By clicking Get My Quotes, I authorize security companies, their dealers and partner companies to contact me about bathroom remodeling 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",
    "VerifyAddress": "false",
    "ContactData": {
        "ZipCode": "12343",
        "State": "NY",
        "IpAddress": "255.255.255.127"
    },
    "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"
    },
    "Person": {
        "BirthDate": "1980-07-27",
        "Gender": "Male",
        "OwnRented": "Own",
        "CreditRating": "Excellent"
    },
    "PersonalLoan": {
        "LoanAmount": "$100 - 500",
        "GrossMonthlyIncome": "2500",
        "IncomeType": "Employed",
        "FrequencyOfIncome": "Every Week",
        "PayCheckNetAmount": "2500",
        "AdditionalIncome": "No",
        "AdditionalIncomeAmount": "100",
        "PayDateOne": "1980-12-09",
        "PayDateTwo": "1980-01-31",
        "MonthlyHousingCosts": "100",
        "MonthlyUnsecuredDebts": "500",
        "HomeEquityAmount": "1111",
        "LiquidAssetsAmount": "9999",
        "RetirementAssetsAmount": "10000",
        "DirectDeposit": "Yes",
        "ExtraInfo": "Hello",
        "LoanDueDate": "1980-01-31",
        "RawLoanAmount": "2500",
        "EmploymentStartDate": "1980-01-31",
        "LastPayDate": "1980-01-31",
        "BankPhoneNumber": "5757171795",
        "LoanPurpose": "Home Improvements",
        "AnnualIncome": "2500",
        "Timeout": "2500"
    }
}

Post
{
    "ApiToken": "xxxx",
    "Vertical": "personalloans",
    "SubId": "FB1",
    "Sub2Id": "",
    "Sub3Id": "",
    "Sub4Id": "",
    "Sub5Id": "",
    "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": "0",
    "TrustedForm": "0",
    "SessionLength": "38",
    "TcpaText": "By clicking Get My Quotes, I authorize security companies, their dealers and partner companies to contact me about bathroom remodeling 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",
    "VerifyAddress": "false",
    "TransactionId": "17D15ADF-2177-4873-9CCC-680E852CDAD4",
     "ContactData": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": "1 Little West 12th",
        "City": "New York",
        "State": "NY",
        "ZipCode": "10114",
        "EmailAddress": "test@testemail.com",
        "PhoneNumber": "6367171795",
        "DayPhoneNumber": "6367171795",
        "IpAddress": "255.255.255.255"
    },
    "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"
    },
     "Person": {
        "FirstName": "John",
        "LastName": "Doe",
        "Gender": "Male",
        "BirthDate": "1980-12-09",
        "CreditRating": "Excellent",
        "CreditScore": "850",
        "MilitaryOrVeteran": "No",
        "BestTimeToCall": "Morning",
        "OwnRented": "Own",
        "YearsAtResidence": "5",
        "MonthsAtResidence": "0",
        "DriversLicense": "Yes",
        "DriversLicenseNumber": "123456789",
        "DriversLicenseState": "NY",
        "BankAccountNumber": "123456789012345",
        "BankRoutingNumber": "123123123",
        "BankAccountType": "Checking",
        "BankName": "North Bank",
        "MonthsAtBank": "5",
        "DebitCard": "No",
        "BankStartDate": "1980-11-30",
        "CalculatedMonthsAtResidence": "1",
        "Job": {
            "CompanyName": "PX",
            "Occupation": "Developer",
            "JobTitle": "Developer",
            "YearsEmployedAtCurrentCompany": "5",
            "MonthsAtEmployer": "9",
            "OfficeStreetAddress": "123 street 1",
            "OfficeCity": "New York",
            "OfficeState": "NY",
            "OfficeZipCode": "90210",
            "OfficePhone": "6367171795",
            "CalculatedMonthsAtEmployer": "1"
            }
        },
    "PersonalLoan": {
        "LoanAmount": "$100 - 500",
        "GrossMonthlyIncome": "2500",
        "IncomeType": "Employed",
        "FrequencyOfIncome": "Every Week",
        "PayCheckNetAmount": "2500",
        "AdditionalIncome": "No",
        "AdditionalIncomeAmount": "100",
        "PayDateOne": "1980-12-09",
        "PayDateTwo": "1980-01-31",
        "MonthlyHousingCosts": "100",
        "MonthlyUnsecuredDebts": "500",
        "HomeEquityAmount": "1111",
        "LiquidAssetsAmount": "9999",
        "RetirementAssetsAmount": "10000",
        "DirectDeposit": "Yes",
        "ExtraInfo": "Hello",
        "LoanDueDate": "1980-01-31",
        "RawLoanAmount": "2500",
        "EmploymentStartDate": "1980-01-31",
        "LastPayDate": "1980-01-31",
        "BankPhoneNumber": "5757171795",
        "LoanPurpose": "Home Improvements",
        "AnnualIncome": "2500",
        "Timeout": "2500"
     }
}

Fields Table

Parameter Required Ping Required Post Accepted Values Description (data type)
ApiToken Yes Yes Provided by PX GUID format
Vertical Yes Yes personalloans String
JornayaLeadId Yes Yes 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
OriginalURL Yes Yes URL where the lead is from String
SessionLength Yes Yes Amount of time spent by the user to fill out the form in seconds Integer
Source Yes Yes Discuss with Acc. Manager 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
UserAgent Yes Yes   String
TcpaText Yes Yes Consent language String
VerifyAddress No No True / False See explanation on this parameter
RespondOnNoSale
 No No True / False See explanation on this parameter
SellResponseURL No No Postback URL See explanation on this parameter
ClickConsentID No No Integer
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 Yes Yes See accepted values list String
ZIPCode Yes Yes 5 digit zip code
EmailAddress No Yes Valid email address String
PhoneNumber No Yes Valid 10 digit phone number without formatting 8887777777
 Integer
DayPhoneNumber No No Valid 10 digit phone number without formatting 8887777777
 Integer
IPAddress Yes Yes Example: 38.88.150.2 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
FirstName No Yes String
LastName No Yes String
BirthDate No No yyyy-mm-dd String
Gender No No Male / Female / Unspecified String
CreditRating Yes Yes
Excellent / Good / Some Problems / Major Problems
 String
CreditScore No No Decimal String
MilitaryOrVeteran
 No No Yes / No String
BestTimeToCall
 No No String
OwnRented
 Yes Yes Own / rented String
YearsAtResidence
 No No Integer String
MonthsAtResidence
 No No See accepted values list String
DriversLicense
 No No Yes / No String
DriversLicenseNumber
 No No String
DriversLicenseState
 No No See accepted values list String
BankAccountNumber
 No No String
BankAccountType
 No No
Checking / Savings
 String
BankName
 
 No No String
MonthsAtBank No No Integer (1 – 360) String
DebitCard
 No No Yes / No String
BankStartDate
 No No yyyy-mm-dd String
CalculatedMonthsAtResidence
 No No String
CompanyName
 No No String
Occupation No No String
JobTitle
 No No String
YearsEmployedAtCurrentCompany
 No No Integer (1 – 100) String
MonthsAtEmployer
 No No Integer (0 – 999) String
OfficeStreetAddress
 No No String
OfficeCity
 No No String
OfficeState
 No No See accepted values list String
OfficeZipCode
 No No 5 digit zip code String
OfficePhone
 No No Valid 10 digit phone number without formatting 8887777777 String
CalculatedMonthsAtEmployer No No String
LoanAmount
 Yes Yes String
GrossMonthlyIncome
 Yes Yes A decimal String
IncomeType
 Yes Yes Employed /  Benefits /  SelfEmployed /  Unemployed String
FrequencyOfIncome
 No No See accepted values list String
PayCheckNetAmount
 No No A decimal String
AdditionalIncome
 No No Yes / No String
AdditionalIncomeAmount No No A decimal String
PayDateOne
 No No yyyy-mm-dd String
PayDateTwo
 No No yyyy-mm-dd String
MonthlyHousingCosts
 No No A decimal String
MonthlyUnsecuredDebts
 No No A decimal String
HomeEquityAmount
 No No A decimal String
LiquidAssetsAmount
 No No A decimal String
RetirementAssetsAmount
 No No A decimal String
DirectDeposit
 No No Yes / No String
ExtraInfo
 No No Free text field String
LoanDueDate
 No No yyyy-mm-dd String
RawLoanAmount
 No No A decimal String
EmploymentStartDate
 No No yyyy-mm-dd String
LastPayDate
 No No yyyy-mm-dd String
BankPhoneNumber
 No No Valid 10 digit phone number without formatting 8887777777 String
LoanPurpose
 No No Free text field String
AnnualIncome
 No No A decimal String
Timeout
 No No A decimal 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.

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

Implementing Brand Explicit Consent

Brand Explicit Consent ensures that consumers can give individual consent to specific advertisers, before the advertisers receive the lead. Leads with the brand included will be sold to a campaign from the scope of those that require brand consent and have a matching brand connected (either directly or through Parent-Alias & Alias-Parent-Alias relations). Implementing Brand Explicit Consent would require adding the Match Ping, a new type of ping that precedes the Ping, to the ‘Ping Post’ flow.

Integrating the Match Ping

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. To get the list of potential brands for lead brand consent, we recommend to integrate MatchPing.

Changes to the Ping

The General Lead data structure is governed by vertical specs. With Brand Explicit Consent, there are a few additions to the Ping lead data structure:

  • MatchPingID should match the one obtained during Match Ping from PX. Can be non-unique if Match Ping results are re-used or empty if Match Ping wasn’t called at all
  • Brand identifiers in the new BrandConsent field supported are Name, PxId, and Uid. Only one identifier should be submitted per brand
  • The brand section can also be omitted fully (in this case, lead still will be accepted and sold to campaigns that do not require brand consent)
  • Lead Post does not require any changes

For additional information on the changes to a Ping in the Brand Explicit Consent Flow, please find more details here.

MonthsAtResidence:

  • 0
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11

LoanAmount:

  • $100 – 500
  • $501 – 1,000
  • $1,001 – 2,500
  • $2,501 – 5,000
  • $5,001 – 10,000
  • $10,001 – 12,500
  • $12,501 – 17,500
  • $17,501 – 20,000
  • $20,001 – 25,000
  • $25,001 – 30,000
  • $30,001 – 35,000
  • $35,001 – 40,000
  • $40,001 – 45,000
  • $45,001 – 50,000

FrequencyOfIncome:

  • Every Week
  • Every Two Weeks
  • Every Month
  • Other
  • Twice Monthly

LoanPurpose:

  • Home Improvements
  • Consolidation
  • Car Purchase
  • Caravan Purchase
  • Holiday
  • Boat Purchase
  • Household Goods
  • Motorcycle Purchase
  • Wedding Expense
  • School Fees
  • Solicitors Fees
  • Cosmetic Surgery
  • Medical Fees
  • Business Loan
  • Mortgage Deposit
  • Livestock Purchase
  • Repay 1st Mortgage and Consolidation
  • Repay 1st Mortgage and Home Improve
  • Further Advance
  • Bridging Loan
  • Business Purchase

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