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

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": [
        "'Roof Type' must not be empty.",
        "'Roof Type' must be one of Asphalt shingle, Wood shingle, Tile, Concrete, Other, Blank. 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>'Roof Type' must not be empty.</string>
      <string>'Roof Type' must be one of Asphalt shingle, Wood shingle, Tile, Concrete, Other, Blank. 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.

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.

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}

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.

YearsAtResidence

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 15
• 20
• 25
• 30

Occupation

• 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

Education

• Bachelors Degree
• Doctorate Degree
• High school diploma
• Masters Degree
• Other
• None
• Some College
• Associate Degree

PropertyType

• Single family
• Apartment
• Duplex
• Condo
• Townhome
• Mobile home

Garage

• Attached 1 car
• Attached 2 car
• Attached 3 car
• Attached carpool
• Detached 1 car
• Detached 2 car
• Detached 3 car
• Detached carpool
• No garage
• Other

Foundation

• Basement fully furnished
• Basement half furnished
• Basement unfurnished
• Crawl space
• Slab
• Other

Bathrooms

• 1
• 1.5
• 2
• 2.5
• 3
• 3.5
• 4
• 4+

PrimaryHeating

• Gas (Forced air)
• Hot water / Steam radiator
• Oil / Coal / Kerosene
• Propane
• Stove

ExteriorWalls

• Brick
• Wood frame
• Stone
• Aluminum siding
• Vinyl siding
• Veneer
• Cinder block
• Stucco
• Other

InsuranceCompany

• 21st Century
• AAA
• AARP
• AIG
• Access Insurance
• AETNA
• AFLAC
• AIU
• Alfa Insurance
• All Risk
• Allianz
• Allied
• Allstate
• American Alliance Insurance
• American Family
• American Home Assurance
• American Insurance
• American International Insurance
• American International Pacific
• American Internacional south
• AMS User Group
• American International South
• American Direct Business Insurance
• American Deposit Insurance
• American Casualty
• American Manufacturers
• American Empire Insurance
• American Financial
• American Health Underwriters
• American Mayflower Insurance
• American Motorists Insurance
• American National
• American Premier Insurance
• American Protection Insurance
• American Automobile Insurance
• American Reliable
• American Republic
• American Savers Plan
• American Service Insurance
• American Skyline Insurance Company
• American Spirit Insurance
• American Standard Insurance
• AmeriPlan
• Ameriprise
• Amica
• Answer Financial
• Anthem
• Arbella
• Armed Forces Insurance
• Associated Indemnity
• Assurant
• Atlanta Casualty
• Atlantic Indemnity
• Atlantis
• Auto Club Insurance Company
• AXA Advisors
• Auto Owners
• Bankers Life and Casualty
• Banner Life
• Best Agency USA
• Blue Cross / Blue Shield
• Brooke Insurance
• Commonwealth
• Company not listed
• Cal Farm Insurance
• California State Automobile Association
• Chubb
• Cigna
• Citizens
• Clarendon
• Clarendon National Insurance
• CNA
• Colonial Insurance
• Comparison Market
• Continental Insurance
• Cotton States
• Country Insurance and Financial Services
• County Insurance and Financial Services
• Countrywide
• Countywide
• CSE Insurance Group
• Dairyland Insurance
• eFinancial
• eHealth Insurance Sercies
• eHealthInsurance Services
• Electric Insurance
• Elephant
• Equitable Life & Casualty Insurance
• Erie Insurance
• Esurance
• Farm Bureau/Farm Family/Rural
• Farmers
• FinanceBox.com
• Fire and Casualty Insurance Co of CT
• Farmers Union
• Fidelity Insurance Company
• Fidelity National
• Fireman’s Fund
• Foremost
• Foresters
• Geico
• AMSUserGroup
• Garden State Life Insurance Company
• GMAC
• Golden Rule Insurance
• Government Employees Insurance
• Government Empoyees Insurance
• Grange
• Great American
• Great West
• Guaranty National Insurance
• Guide One Insurance
• Hanover Lloyd’s Insurance Company
• The Hartford
• Guardian
• Guideone
• Hartford AARP
• Health Benefits Direct
• Health Care Solutions
• Health Choice One
• Health Net
• Health Plus of AmericaHealthMarkets
• HealthShare American
• Horace Mann
• Horace Mann Insurance
• Humana
• IFA Auto Insurance
• IGF Insurance
• IDS
• IHIAA
• Infinity Insurance
• Insurance Insight
• Infinity National Insurance
• Infinity Select Insurance
• Insphere Insurance Solutions
• Insurance Shopper, Inc
• Insurance.com
• Integon
• Iroquois Group
• John Hancock
• Kaiser Permanente
• Kemper Lloyds Insurance
• Landmark American Insurance
• Leader Insurance
• Leader Preferred Insurance
• Leader Specialty Insurance
• Liberty Insurance Corp
• Liberty Mutual
• Liberty National
• Liberty Northwest
• Liberty Nothwest
• Lincoln Benefit Life
• Lumbermens Mutual
• Maryland Casualty
• Mass Mutual
• Mega/Midwest
• Matrix Direct
• Mercury
• MetLife Auto and Home
• Metropolitan Insurance Co.
• Mid Century Insurance
• Continent Casualty
• Middlesex Insurance
• Midland National Life
• Mutual Insurance
• National Insurance
• Miller Mutual
• Modern Woodmen of America
• Mutual of New York
• Mutual Of Omaha
• National Ben Franklin Insurance
• National Casualty
• Continental Casualty
• Continental Divide Insurance
• National Continental Insurance
• National Fire Insurance
• National Health Insurance
• National Indemnity
• National Union Fire Insurance
• Nationwide
• New England Financial
• New York Life Insurance
• Northwestern Mutual Life
• Nortwestern Mutual Life
• Norhwestern Pacific Indemnity
• Northwestern Pacific Indemnity
• Omni Insurance
• Orion Insurance
• Pacific Insurance
• Pafco General Insurance
• Patriot General Insurance
• Peak Property and Casualty Insurance
• PEMCO Insurance
• Physicians
• Penn Mutual
• Pennsylvania life
• Premier
• Primerica
• Principal Financial
• Progressive
• Protective Life
• Prudential Insurance Co.
• RBC Liberty
• Reliance Insurance
• Republic Indemnity
• Response Insurance
• SAFECO
• Safeway Insurance
• Security Insurance
• Senior Market Sales
• Sentinel Insurance
• Sentry
• Shelter
• St. Paul Insurance
• Standard File Insurance Company
• Standard Fire Insurance Company
• State and County Mutual Fire Insurance
• State Farm
• State National
• Superior American Insurance
• Superior Guaranty Insurance
• Superior Insurance
• Sure Health Plans
• The Ahbe Group
• The General
• TICO Insurance
• TICO Insurance1
• TIG Countrywide Insurance
• Titan
• TransAmerica
• Travelers
• State Consumer Insurance
• Twin City Fire Insurance
• UniCare
• United Insurance
• United American/Farm and Ranch
• United Life Group
• United Pacific Insurance
• United Security
• United Services Automobile Association
• Unitrin Direct
• Universal Underwriters Insurance
• US Financial
• US Health Group
• USA Benefits / Continental General
• USA Benefits/Continental General
• USAA
• USF and G
• Viking Insurance
• Western and Southern Life
• Western Mutual
• William Penn
• Windsor Insurance
• Woodlands Financial Group
• Zurich North America
• Currently not insured

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