Introduction
This document describes how to post full shared health insurance 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
Fields Table
Responses
PX responds with accurate feedback on how to update your request for it to be accepted by the API.
Success – Ping
{
"TransactionId": "394d89a8-fae9-4a08-92cd-b5bf97f8455e",
"Success": true,
"Payout": null,
"Message": null,
"Errors": null,
"Sold": null,
"RedirectUrl": null,
"BuyerRawResponse": null,
"Environment": "Testing",
"Legs": [
{
"Name": null,
"Hash": "462c49f8-9288-4d7a-aab6-48a6406a0d82",
"Payout": 12.34,
"Status": "Success"
},
{
"Name": null,
"Hash": "cb3be58b-ef2f-4b5d-8418-e68f3c5872ee",
"Payout": 23.45,
"Status": "Success"
},
{
"Name": null,
"Hash": "303e7ec3-589f-497e-9107-2c04efaac98e",
"Payout": 34.56,
"Status": "Success"
}
]
}
<?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>643fd719-bd29-4825-b859-e172bc31acf1</TransactionId>
<Success>true</Success>
<Payout xsi:nil="true" />
<Sold xsi:nil="true" />
<Environment>Testing</Environment>
<Legs>
<Leg>
<Hash>f37eff48-6f79-4174-b770-9c6ed7166d1f</Hash>
<Payout>12.34</Payout>
<Status>Success</Status>
</Leg>
<Leg>
<Hash>adc73637-6c51-446d-8b03-c1ef1d7aa94e</Hash>
<Payout>23.45</Payout>
<Status>Success</Status>
</Leg>
<Leg>
<Hash>df053300-a1cc-4e4b-8423-4abcca644e72</Hash>
<Payout>34.56</Payout>
<Status>Success</Status>
</Leg>
</Legs>
</Result>
Success – Post
{
"TransactionId": "394d89a8-fae9-4a08-92cd-b5bf97f8455e",
"Success": true,
"Payout": null,
"Message": null,
"Errors": null,
"Sold": null,
"RedirectUrl": null,
"BuyerRawResponse": null,
"Environment": "Testing",
"Legs": [
{
"Name": null,
"Hash": "ebd3d4aa-d3dc-448a-9947-034b1dbd3c65",
"Payout": 12.34,
"Status": "Success"
},
{
"Name": null,
"Hash": "3d4c2e34-17d9-4c65-9094-9aa6682f6a82",
"Payout": 23.45,
"Status": "Success"
},
{
"Name": null,
"Hash": "7940786d-5f2d-48f4-a896-9bd53bb9c6f8",
"Payout": 34.56,
"Status": "Success"
}
]
}
<?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>790B52B0-FE5D-48E3-B81C-91992017A659</TransactionId>
<Success>true</Success>
<Payout xsi:nil="true" />
<Sold xsi:nil="true" />
<Environment>Testing</Environment>
<Legs>
<Leg>
<Hash>e3f54b53-39f0-4fd7-ad9c-3786ba5cafc1</Hash>
<Payout>12.34</Payout>
<Status>Success</Status>
</Leg>
<Leg>
<Hash>764d649e-0c7f-4274-8558-3aba963c28e2</Hash>
<Payout>23.45</Payout>
<Status>Success</Status>
</Leg>
<Leg>
<Hash>be713280-abb4-4975-8c78-ae2921a4cc9c</Hash>
<Payout>34.56</Payout>
<Status>Success</Status>
</Leg>
</Legs>
</Result>
Failure
{
"TransactionId": "49CE4DB7-775B-405B-BBBD-B23FB003073A",
"Success": false,
"Payout": null,
"Message": "BadRequest",
"Errors": [
'High Cholesterol' must be one of Yes, No. 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>'High Cholesterol' must be one of Yes, No. 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.
VerifyAddress
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 initial 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
- 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
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
| 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 |
YearsAtResidence
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 15
- 20
- 25
- 30
RelationshipToApplicant
- Self
- Spouse
- Child
- Sibling
- Parent
- Grandparent
- Grandchild
- Other
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
CoverageType
- COBRA
- Dental Only
- Discount Plan
- Individual Family
- Maternity Only
- Medicaid
- Medicare Supplement
- Prescription Only
- Short Term
- Vision Only
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.
Full Shared
PX provides you with the ability to sell us a specific leg only. On the ping response we will tell you the bid per every leg (by name or hashed), and, in the response, should this price be satisfactory for you, you can initiate the post and thus selling us that leg – all through one API ping/post call.
Parameters explained
- OpenSlots – This indicates how many times the lead can still be sold by PX
- Include/Exclude – What action will PX take on this lead? For Full Shared it will always be include since we are including this buyer in the bidding process.
- Name – This is the leg name of the buyer.
- Hash – This is the hashed leg name of the buyer. Hashing is done using the
- SHA-1 hashing method. The hashed value needs to be the buyer’s 1800 phone number.
Full Shared Lead Flow
- Publisher pings PX with a ping request
- PX responds with bids per buyer
- Publisher decides which buyers to include on the post and forms the post request including the buyer’s leg / hashed leg names
- PX responds with the result of the sale per leg name.
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 |