Direct Post – Exclusive

Introduction

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.

Post URL: https://leadapi.px.com/api/lead/directpost

Forcing a success: When 90170 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

Examples

Post

<Lead>
  <ApiToken>xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx</ApiToken>
  <Vertical>Debtconsolidation</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://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 agree to the Terms of Service and Privacy Policy and authorize Debt consolidation companies, their agents and marketing partners to contact me about Debt consolidation and other non-debt consolidation offers by telephone calls, email and text messages to the number and email address I provided above. I agree to receive telemarketing calls, and pre-recorded messages via an autodialed phone system, even if my telephone number is a mobile number that is currently listed on any state, federal or corporate “Do Not Call” list. I understand that my consent is not a condition of purchase of any goods or services and that standard message and data rates may apply.</TcpaText> 
  <ContactData> 
    <FirstName>John</FirstName> 
    <LastName>Doe</LastName> 
    <Address>1 Little West 12th</Address> 
    <City>New York</City> <State>NY</State> 
    <ZipCode>10005</ZipCode> 
    <EmailAddress>testlead@somedomain.com</EmailAddress> 
    <PhoneNumber>6367171795</PhoneNumber> 
    <DayPhoneNumber>6367171795</DayPhoneNumber> 
    <IpAddress>255.255.255.255</IpAddress> </ContactData>
    <State>NY</State>
    <ZipCode>10005</ZipCode>
    <IpAddress>255.255.255.255</IpAddress>
  </ContactData>
  <Person>
    <Gender></Gender>
    <BirthDate></BirthDate>
    <CreditRating>Excellent</CreditRating>
    <CreditScore>850</CreditScore>
    <MilitaryOrVeteran>No</MilitaryOrVeteran>
    <BestTimeToCall>Any time</BestTimeToCall>
    <Job>
      <CompanyName>PX</CompanyName>
      <Occupation>Developer</Occupation>
      <JobTitle>YearsEmployedAtCurrentCompany</JobTitle>
      <YearsEmployedAtCurrentCompany>5</YearsEmployedAtCurrentCompany>
      <MonthsAtEmployer>9</MonthsAtEmployer>
      <OfficeStreetAddress>123 street 1</OfficeStreetAddress>
      <OfficeCity>New York</OfficeCity>
      <OfficeState>NY</OfficeState>
      <OfficeZipCode>90210</OfficeZipCode>
      <OfficePhone>6367171795</OfficePhone>
      </Job>
    <OwnRented>Own</OwnRented>
    <YearsAtResidence>5</YearsAtResidence>
    <MonthsAtResidence>0</MonthsAtResidence>
    <DriversLicense>No</DriversLicense>
    <DriversLicenseState>NY</DriversLicenseState>
    <BankAccountType>Checking</BankAccountType>
    <BankName>North Bank</BankName>
    <MonthsAtBank>5</MonthsAtBank>
    <DebitCard>No</DebitCard>
    <BankStartDate>1980-11-30</BankStartDate>
  </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>
    <PersonalLoan>
      <DebtAmount>$100 - 500</DebtAmount>
      <GrossMonthlyIncome>2500</GrossMonthlyIncome>
      <IncomeType>Employed</IncomeType>
      <FrequencyOfIncome>Every Week</FrequencyOfIncome>
      <PayCheckNetAmount>2500</PayCheckNetAmount>
      <AdditionalIncome>No</AdditionalIncome>
      <AdditionalIncomeAmount>100</AdditionalIncomeAmount>
      <PayDateOne>1980-12-09</PayDateOne>
      <PayDateTwo>1980-01-31</PayDateTwo>
      <MonthlyHousingCosts>100</MonthlyHousingCosts>
      <MonthlyUnsecuredDebts>500</MonthlyUnsecuredDebts>
      <HomeEquityAmount>1111</HomeEquityAmount>
      <LiquidAssetsAmount>9999</LiquidAssetsAmount>
      <RetirementAssetsAmount>10000</RetirementAssetsAmount>
      <DirectDeposit>Yes</DirectDeposit>
      <ExtraInfo>Hello</ExtraInfo>
      <LoanDueDate>1980-01-31</LoanDueDate>
      <RawLoanAmount>2500</RawLoanAmount>
      <EmploymentStartDate>1980-01-31</EmploymentStartDate>
      <LastPayDate>1980-01-31</LastPayDate>
      <LoanPurpose>Home Improvements</LoanPurpose>
      <AnnualIncome>2500</AnnualIncome>
      <Timeout>2500</Timeout>
      <DebtType>Consolidation</DebtType>
    </PersonalLoan>
</Lead>

Post

{
    "ApiToken": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
    "Vertical": "Debtconsolidation",
    "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://exampleUrl.com",
    "Source": "Social",
    "JornayaLeadId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "TrustedForm": "https://cert.trustedform.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "SessionLength": "38",
    "TcpaText": "By clicking Get My Quotes, I agree to the Terms of Service and Privacy Policy and authorize Debt consolidation companies, their agents and marketing partners to contact me about Debt consolidation and other non-debt consolidation offers by telephone calls, email and text messages to the number and email address I provided above. I agree to receive telemarketing calls, and pre-recorded messages via an autodialed phone system, even if my telephone number is a mobile number that is currently listed on any state, federal or corporate “Do Not Call” list. I understand that my consent is not a condition of purchase of any goods or services and that standard message and data rates may apply.",
    "VerifyAddress": "false",
    "SellResponseURL": "https://example.com?TransactionId={transactionid}&Payout={payout}&Result={Result}&Reason={Reason}&SubID={subid}",
    "ContactData": {
        "FirstName": "John",
        "LastName": "Doe",
        "Address": "1 Little West 12th",
        "City": "New York",
        "State": "NY",
        "ZipCode": "10005",
        "EmailAddress": "testlead11@somedomain.com",
        "PhoneNumber": "6367171795",
        "DayPhoneNumber": "6367171795",
        "IpAddress": "255.255.255.255"
    },
     "Person": {
        "FirstName": "John",
        "LastName": "Doe",
        "Gender": "Unspecified",
        "BirthDate": "1980-12-09",
        "CreditRating": "Excellent",
        "CreditScore": "850",
        "MilitaryOrVeteran": "No",
        "BestTimeToCall": "Any time",
        "Job": {
            "CompanyName": "PX",
            "Occupation": "Developer",
            "JobTitle": "YearsEmployedAtCurrentCompany",
            "YearsEmployedAtCurrentCompany": "5",
            "MonthsAtEmployer": "9",
            "OfficeStreetAddress": "123 street 1",
            "OfficeCity": "New York",
            "OfficeState": "NY",
            "OfficeZipCode": "90210",
            "OfficePhone": "6367171795"
            },
        "OwnRented": "Own",
        "YearsAtResidence": "5",
        "MonthsAtResidence": "0",
        "DriversLicense": "No",
        "DriversLicenseState": "NY",
        "BankAccountType": "Checking",
        "BankName": "North Bank",
        "MonthsAtBank": "5",
        "DebitCard": "No",
        "BankStartDate": "1980-11-30"
        },
    "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"
        },
    "PersonalLoan": {
        "DebtAmount": "$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",
        "LoanPurpose": "Home Improvements",
        "AnnualIncome": "2500",
        "Timeout": "2500",
        "DebtType": "Consolidation"
    }
}

Fields Table

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

Success

{
    "TransactionId": "50cd75f6-85ac-4f0c-85a1-8b42e2a9135e",
    "MatchPingId": null,
    "Success": true,
    "Payout": null,
    "Message": null,
    "Errors": null,
    "Sold": null,
    "RedirectUrl": null,
    "BuyerRawResponse": null,
    "BuyerGuid": null,
    "Environment": "Testing",
    "Legs": null,
    "Brands": null
}

<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <TransactionId>6e3be8b2-ba70-4c1d-9a26-2d407beb3144</TransactionId>
    <Success>true</Success>
    <Payout xsi:nil="true" />
    <Sold xsi:nil="true" />
    <BuyerGuid 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

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 Direct Post.

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 Direct Post

The General Lead data structure is governed by vertical specs. With Brand Explicit Consent, there are a few additions to the Direct Post 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)

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

MonthsAtEmployer

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

MonthsAtResidence

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

DebtAmount

• $100 – 500
• $501 – 1,000
• $1,001 – 2,500
• $2,501 – 5,000
• $5,001 – 10,000
• $10,001 – 12,500
• $12,501 – 15,000
• $15,001 – 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
• $50,001 – 60,000

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
• Debt Settlement
• Debt Counseling
• Tax Debt
• Student Loan Consolidation

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