INTRODUCTION TO HEALTH/MEDICARE INSURANCE PING/POST

Health Insurance is a two-step integration process. Commonly, it is referred to as ping/post, i.e. first you send us a ‘ping’ and we respond with a bid (or outright rejection). Assuming we are the winning bidder, you would then ‘post’ the lead data, along with the <Lead_ID> code you received in the ping response.

PING:

What is a Ping?

A Ping is a call to our API with all of the lead data EXCEPT the personal information (PI). It’s purpose is to determine if there is any interest in purchasing the lead, and if there is, to establish the price we would be willing to pay if a subsequent Post for the same lead is accepted.

pingPostLead

URL for HTTP GET or POST methods: https://plm.leadportal.com/api.php

This function has three modes:

Ping mode: in “ping” mode you can submit partial lead information as defined in “Ping Required” column of the specification to check if lead can be matched.
Post mode: Based on the “ping” response (matched, unmatched) you can then post the full lead info. Required fields are defined in “Post Required” column of the specification.
Full mode: This mode can be used if one has the full lead and would like to submit it just once but system still does ping and then post steps internally. In this case the lead must contain all required values for ping and for post mode, except Lead_ID.

Note:

Example Column – examples of the data to be passed in the relevant fields
Highlighted instructions are given for ‘YES’ answers to Additional Driver, Additional Vehicles, Currently Insured and Incidents. If further additional fields are required ask your PLM contact for instructions.
NO – this denotes a field that is optional but preferred. Pings with these parameters bring higher payouts and can be offered to a significantly larger pool of buyers.
Cost: optionally, a lead cost can be submitted in the ping request. It then overrides lead cost values in the system. Cost should be sent only in ping mode, in post mode it is ignored. It is also ignored if equal or less then zero value is sent.

Health Insurance Lead Type (if sending Medicare leads then please hardcode these fields)

Ping Required	Post Required	Field name	Values	Example
YES	YES	Key	string (provided by site admin)	c65KclcVojZodK5ojoW9x-J8sfJGjvxUEcjo.cgJo-W59d3uFePP
YES	YES	API_Action	name of the API function to call	pingPostLead
YES	YES	Mode	string, one of: ping post full	ping
NO	NO	Cost	real number greater than 0	2.55
NO	YES	Lead_ID	Lead ID number received in response of “ping” mode.	1234
NO	NO	Allowed_Times_Sold	Max. number of times a lead can be sold.	2
NO	NO	Return_Hash_Type	Hashes of the matches sent back in response. Must be used together with Return_Hash_Value_TypeAllowed values: sha1, md5.	sha1
NO	NO	Return_Hash_Value_Type	Hashes of the matches sent back in response. Must be used together with Return_Hash_TypeAllowed values: email, phone, company, promotionCode, partnerGroup	email
NO	NO	Skip_Partner_ID	List the partners to skip in processing (exclude from being matched). Comma delimited list of values.	142,1543,225
YES (only if dynamic pricing)	NO	Return_Best_Price	1 (Only if vendor is on dynamic pricing)	1
YES	YES	TYPE	31	31
NO	NO	Test_Lead	1 (Only when testing)	1
NO	NO	Skip_XSL	Do not include XSL path in XML response	1
NO	NO	Match_With_Partner_ID	Comma separeated list with Client IDs to only match with	22,456
NO	NO	Redirect_URL	Set your redirect URL.	http://www.yoursite.com/
YES	NO	SRC	Assigned by lead company	health_ins_
NO	YES	Landing_Page	url lead was generated on initially	http://ratechecker.com/health-insurance/’
NO	YES	IP_Address	Varchar (30)	75.2.92.149
YES	NO	Sub_ID	Varchar (100) Your unique reference for the lead	12
YES	NO	Pub_ID	Varchar (100) Should denote internal sources of traffic/leads for optimization	12345
NO	NO	Optout	Varchar (20)	Optout
YES	NO	TCPA_Consent	Indicates whether or not the consumer was presented with, and accepted, unambiguous consent to be contacted via automated telephone systems pursuant to TCPA requirements. Click here for more information.Set. Allowed values: Yes No	Yes
YES	NO	TCPA_Language	Contains the TCPA language the consumer was presented with on the form where their information was submitted, Click here for more information.	‘By submitting this form…’
YES	NO		Unique LeadiD as generated by LeadiD.com	8336E01B-527A-45B6-E5C3-75511E3E5474
NO	NO	UserAgent	Varchar (400)	UserAgent
NO	YES	First_Name	Varchar (100)	First_Name
NO	YES	Last_Name	Varchar (100)	Last_Name
NO	YES	Address	Varchar (100)	123 Main St.
NO	NO	Address2	Varchar (100)	Address2
YES	NO	City	Varchar (100)	Chicago
YES	NO	State	Valid US state abbreviation. Varchar (2)	IL
YES	NO	Zip	Valid ZipCode. 5 digits	60610
NO	YES	Email	Valid email. Varchar (100)	test@nags.us
NO	YES	Phone	Valid phone. 10 digits	3125559202
YES	NO	Gender	Set. Allowed values: Male Female	Male
NO	NO	CellPhone	Valid phone. 10 digits	3125553717
YES	NO	DOB	Valid date. m/d/Y	12/23/1980
YES	NO	Age	Integer	35
YES	NO	Currently_Taking_Medication	Set. Allowed values: Yes No	No
YES	NO	Type_Of_Lead	Use these hardcoded values for Medicare. Set. Allowed values: Health Insurance Medicare	Health Insurance
YES	NO	Tobacco_User	Set. Allowed values: Yes No	No
YES	NO	Height_Feet	Set. Allowed values: 4 5 6 7	5
YES	NO	Height_Inches	Set. Allowed values: 0 1 2 3 4 5 6 7 8 9 10 11	10
YES	NO	Weight	Integer – lbs	160
YES	NO	Household_Size	Set. Allowed values: 1 2 3 4 5 6 7 8	4
YES	NO	Estimated_Household_Income	Integer – monthly	2000
YES	NO	Currently_Insured	Set. Allowed values: Yes No	No
YES	NO	Spouse_Included	Set. Allowed values: Yes No	No
YES	NO	Children_Included	Set. Allowed values: Yes No	Yes
YES	NO	Expecting_Parent	Set. Allowed values: Yes No	Yes

XML Post:

You can send the data as XML post. You can send the XML data to the following URL.

XML Post URL: https://plm.leadportal.com/apiXML.php

Test XML Post URL: https://plm.leadportal.com/apiXML.php – for testing use xml node Test_Lead and value 1

All required values are being evaluated as stated in the table above. The XML data structure to be posted is as follows.

<?xml version="1.0"?>
<Request>
    <Key></Key>
    <API_Action></API_Action>
    <Mode></Mode>
    <Cost></Cost>
    <Allowed_Times_Sold></Allowed_Times_Sold>
    <Return_Hash_Type></Return_Hash_Type>
    <Return_Hash_Value_Type></Return_Hash_Value_Type>
    <Lead_ID></Lead_ID>
    <Skip_Partner_ID></Skip_Partner_ID>
    <Return_Best_Price></Return_Best_Price>
    <TYPE></TYPE>
    <Test_Lead></Test_Lead>
    <Skip_XSL></Skip_XSL>
    <Match_With_Partner_ID></Match_With_Partner_ID>
    <Redirect_URL></Redirect_URL>
    <Data>
        <SRC></SRC>
        <Landing_Page></Landing_Page>
        <IP_Address></IP_Address>
        <Sub_ID></Sub_ID>
        <Pub_ID></Pub_ID>
        <Optout></Optout>
        <Unique_Identifier></Unique_Identifier>
        <Currently_Taking_Medication></Currently_Taking_Medication>
        <TCPA_Consent></TCPA_Consent>
        <TCPA_Language></TCPA_Language>
        <universal_leadid></universal_leadid>
        <First_Name></First_Name>
        <Last_Name></Last_Name>
        <Address></Address>
        <City></City>
        <State></State>
        <Zip></Zip>
        <Phone></Phone>
        <Email></Email>
        <Gender></Gender>
        <DOB></DOB>
        <Age></Age>
        <Type_Of_Lead></Type_Of_Lead>
        <Tobacco_User></Tobacco_User>
        <Height_Feet></Height_Feet>
        <Height_Inches></Height_Inches>
        <Weight></Weight>
        <Household_Size></Household_Size>
        <Estimated_Household_Income></Estimated_Household_Income>
        <Currently_Insured></Currently_Insured>
        <Spouse_Included></Spouse_Included>
        <Children_Included></Children_Included>
        <Expecting_Parent></Expecting_Parent>
    </Data>
    <Matches>
        <Match ValueType="promotionCode" HashType="plain">test code</Match>
        <Match ValueType="promotionCode" HashType="plain">12345</Match>
    </Matches>
    <Match_With_Partner_Hashes>
        <Selected_Partner_Hash ValueType="company" HashType="md5">ewd5692602fc4sa545e4feb0ew3964c5</Selected_Partner_Hash>
        <Selected_Partner_Hash HashType="md5" ValueType="company">f26e492602fc4b4077feb0d80d3964c5</Selected_Partner_Hash>
    </Match_With_Partner_Hashes>
</Request>

Note: To use the Matches and/or Match_With_Partner_Hashes functionality, you must use the XML Post method of this API.

Tag Name	Description	Note
Data	Put appropriate lead data tags	The set of data tags depends on lead type
Matches	Matches made by vendor	When you sold the lead already put information about your matches here. This section is not required.
Match	Information about your match	Put hashed or unhashed value of the phone or email or company, etc.
ValueType	The property of Match tag	Description of data type provided. Allowed values: email, phone, company, promotionCode, partnerGroup (use group ID for partnerGroup)
HashType	The property of Match tag	Description of hash type provided. Allowed values: sha1, md5.
Match_With_Partner_Hashes	Request to match the lead with specific partners	Hashes must be selected from the list of hashes provided in ping response when using Return Hashes option. HashType and ValueType of the Selected_Partner_Hash tag must be the same as used in the Return Hashes option in ping.
Selected_Partner_Hash	The hash of a partner a lead is requested to be matched with	Hash must be selected from the list of hashes provided on ping when using Return Hashes option
HashType	The property of Selected_Partner_Hash tag	Description of hash type provided. Allowed values: sha1, md5.
ValueType	The property of Selected_Partner_Hash tag	Description of data type provided. Allowed values: email, phone, company, promotionCode, partnerGroup (use group ID for partnerGroup)

Note: State is NOT required on the ping as long as a valid zip code is sent. We will do a zip code -> state look up on our end.

Response Matched Example:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>Matched</status>
    <lead_id>874</lead_id>
    <price>25</price>
</response>

Response Matched Example with Allowed_Times_Sold used:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>Matched</status>
    <lead_id>874</lead_id>
    <matches>5</matches>
</response>

Response Matched Example with sent back hashes:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>Matched</status>
    <lead_id>348</lead_id>
    <hashes>
        <hash HashType="md5" ValueType="email">8561c83bb23a3f77345fa2b6b50b1f4e</hash>
        <hash HashType="md5" ValueType="email">8561c83bb23a3f77345fa2b6b50b1f4e</hash>
    </hashes>
</response>

Response Unmatched Example:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>Unmatched</status>
    <lead_id>874</lead_id>
</response>

Name	Description	Note
status	Result of the action
lead_id	ID number of successfully submitted lead	Returned on success
price	The best price at which a lead can be accepted.	Returned on success and only if Return_Best_Price was submitted in “ping”

Response – error:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>Error</status>
    <error>Required value First_Name is missing</error>
</response>

Name	Description	Note
status	Result of the action
error	Error message	Returned on error