Ping Post – Full Shared

API 2.0 Specifications for Medicare

Introduction

This document describes how to post full shared medicare 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": "Medicare",
	"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 insurance companies, their agents and marketing partners to contact me about medicare insurance and other non-insurance 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",
	"FirstTimeBuyer": "Yes",
	"SiteLicenseNumber": "MULTI-PLAN_ABCd12EFgh2022_C",
	"ContactData": {
		"ZipCode": "90170",
		"State": "NY",
		"IpAddress": "255.255.255.127",
	},
	"Person": {
		"BirthDate": "1945-01-01",
		"Gender": "Male",
		"RelationshipToApplicant": "Self",
		"HouseHoldIncome": "$30,000 - $44,999",
		"HouseHoldSize": "5",
		"Product": "(MS) Medicare Supplement",
		"MaritalStatus": "Single",
		"DeniedInsurance": "No",
		"USResidence": "True",
		"Height_FT": "5",
		"Height_Inch": "9",
		"Weight": "165",
		"Student": "False",
		"Occupation": "Employeed",
		"Education": "Bachelors Degree",
		"HasMedicareCard": "No",
		"EligibleDisability": "No",
		"CurrentPolicy": "Other",
		"Conditions": {
			"HighCholesterol": "No",
			"PulmonaryDisease": "No",
			"VascularDisease": "No",
			"AIDSHIV": "No",
			"KidneyDisease": "No",
			"Asthma": "No",
			"Cancer": "No",
			"Depression": "No",
			"Diabetes": "No",
			"HeartDisease": "No",
			"LiverDisease": "No",
			"HighBloodPressure": "No",
			"MentalIllness": "No",
			"Stroke": "No",
			"Alzheimer": "No",
			"AlcoholAbuse": "No"
		},
		"MedicalHistory": {
			"Hospitalized": "No",
			"Pregnant": "No",
			"Smoker": "No",
			"Alcoholabstain": "No"
		}
	},
	"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"
	},
	"Distribution": {
		"OpenSlots": "5"
	}
}

Post
{
	"ApiToken": "xxxx",
	"Vertical": "Medicare",
	"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 insurance companies, their agents and marketing partners to contact me about medicare insurance and other non-insurance 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",
	"TransactionId": "xxxx",
	"FirstTimeBuyer": "Yes",
	"SiteLicenseNumber": "MULTI-PLAN_ABCd12EFgh2022_C",
	"ContactData": {
		"ZipCode": "90170",
		"State": "NY",
		"Address": "Wall st. 5",
		"IpAddress": "255.255.255.127",
		"FirstName": "John",
		"LastName": "Doe",
		"City": "New York",
		"PhoneNumber": "6467171795",
		"EmailAddress": "testlead@somedomain.com"
	},
	"Person": {
		"BirthDate": "1945-01-01",
		"Gender": "Male",
		"RelationshipToApplicant": "Self",
		"HouseHoldIncome": "$30,000 - $44,999",
		"HouseHoldSize": "5",
		"Product": "(MS) Medicare Supplement",
		"MaritalStatus": "Single",
		"DeniedInsurance": "No",
		"USResidence": "True",
		"Height_FT": "5",
		"Height_Inch": "9",
		"Weight": "165",
		"Student": "False",
		"Occupation": "Employeed",
		"Education": "Bachelors Degree",
		"HasMedicareCard": "No",
		"EligibleDisability": "No",
		"CurrentPolicy": "Other",
		"Conditions": {
			"HighCholesterol": "No",
			"PulmonaryDisease": "No",
			"VascularDisease": "No",
			"AIDSHIV": "No",
			"KidneyDisease": "No",
			"Asthma": "No",
			"Cancer": "No",
			"Depression": "No",
			"Diabetes": "No",
			"HeartDisease": "No",
			"LiverDisease": "No",
			"HighBloodPressure": "No",
			"MentalIllness": "No",
			"Stroke": "No",
			"Alzheimer": "No",
			"AlcoholAbuse": "No"
		},
		"MedicalHistory": {
			"Hospitalized": "No",
			"Pregnant": "No",
			"Smoker": "No",
			"Alcoholabstain": "No"
		}
	},
	"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"
	},
	"Distribution": {
		"Include": [{
			"Name": "Leg12",
			"Hash": "462c49f8-9288-4d7a-aab6-48a6406a0d82"
		}]
	}
}

Fields Table

Parameter Required Ping Required Post Accepted Values
 Description (data type)
ApiToken Yes Yes Provided by PX GUID format
Vertical Yes Yes Medicare 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
OriginalURL Yes Yes URL where the lead is from String
Source Yes Yes Discuss with Acc. Manager String
JornayaLeadId Yes Yes Jornaya LeadId (GUID format) See link on how to implement on form
Trustedform
 Yes Yes TrustedForm Cert. URL. https://cert.trustedform.com/ ID See link on how to implement on form
ClickConsentID No No String
SessionLength Yes Yes Amount of time spent by the user to fill out the form in seconds String
TcpaText Yes Yes Consent language String
VerifyAddress No No True / False String
TransactionId No Yes Retrieve from Ping Response GUID format
FirstTimeBuyer
 Yes Yes Yes/No String
SiteLicenseNumber
 No No  The SMID related to the CMS approval String
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 String
EmailAddress No Yes Valid email address String
PhoneNumber No Yes Valid 10 digit phone number without formatting 8887777777 Integer
DayPhoneNumber No Yes Valid 10 digit phone number without formatting 8887777777 Integer
IpAddress Yes Yes Example: 38.88.150.2 Integer
BirthDate Yes Yes YYYY-MM-DD String
Gender Yes Yes Male / Female String
RelationshipToApplicant Yes Yes See accepted values String
HouseHoldIncome Yes Yes Below $30,000 / $30,000 – $44,999 / $45,000 – $59,999 /
$60,000 – $74,999 /
Above $75,000 		String
HouseHoldSize Yes Yes  Number String
Product Yes Yes (MO) Medicare Original /
(MA) Medicare Advantage /
(MD) Medicare Part D /
(MS) Medicare Supplement		 String
MaritalStatus No No Divorced / Married / Separated / Single / Widowed String
DeniedInsurance No No Yes / No String
USResidence No No True / False Boolean
Height_FT No No Integer
Height_Inch No No Integer
Weight No No Weight in pounds Integer
Student No No True / False Boolean
Occupation No No See accepted values String
Education No No See accepted values String
HasMedicareCard No No Yes / No String
EligibleDisability No No Yes / No String
CurrentPolicy
 No No See accepted values String
HighCholesterol
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
PulmonaryDisease
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
VascularDisease
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
AIDSHIV
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
KidneyDisease
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
Asthma
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
Cancer
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
Depression
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
Diabetes
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
HeartDisease
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
LiverDisease
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
HighBloodPressure
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
MentalIllness
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
Stroke Yes, when product MA or MS Yes, when product MA or MS Yes / No String
Alzheimer
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
AlcoholAbuse
 Yes, when product MA or MS Yes, when product MA or MS Yes / No String
Hospitalized No No Yes / No String
Pregnant No No Yes / No String
Smoker No No Yes / No String
Alcoholabstain No No Yes / No 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 Please pass the Marketing Angle here. See accepted values 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
OpenSlots Yes No String
See explanation on full shared
Include No Yes String
See explanation on full shared
Name Yes, if Hash is not used Yes, if Hash is not used Leg name String
See explanation on full shared
Hash Yes, if Name is not used Yes, if Name is not used SHA-1 Hashed leg name String
See explanation on full shared

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": [
        
    ]
    "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

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

CurrentPolicy

  • United Healthcare
  • Humana
  • BCBS plans
  • CVS Health
  • Kaiser Permanente
  • Cigna
  • Centene
  • Other

Marketing Angle (passed in Custom Field4)

Value Example
ANOC “Your Medicare plan is changing – see what’s new for next year before AEP.”
Communications “Get important updates about your Medicare plan straight to your inbox.”
CSNP “Special plans designed for people with chronic conditions like diabetes and heart disease.”
Dental “Get dental coverage that helps pay for cleanings, x-rays, and even dentures.”
Disaster “If you’ve been affected by a declared disaster, you may qualify for a Special Enrollment Period.”
DSNP
Flex card  “Use your Medicare Flex Card to pay for health-related expenses with ease.”
Food card “Many Medicare Advantage plans now include a food allowance card – shop groceries at no cost to you.”
OTC “Get $100 per quarter for everyday health essentials like pain relievers, vitamins, and first aid supplies.”
Part B “Put money back in your Social Security check with a Part B giveback plan.”
Plan Comparison “Compare top-rated Medicare Advantage plans in your ZIP code today.”
Relocation “Moving? Don’t miss your chance to update your Medicare plan with relocation benefits.”
T65 “Turning 65? Enroll now to take full advantage of your Medicare benefits.”

 

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.

Undersold

When leads are being sold to PX that have already been sold to another lead buyer, the undersold method should be used.
Add the following parameters to the request body:

  • OpenSlots – indicates the number of times this lead can still be sold;
  • Name / Hash – indicates to which buyer this lead has already been sold. These buyers won’t be taken into account in the bidding process

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