Direct Post – Exclusive

API 1.0 Specifications for Pet insurance

Introduction

This document describes how to post exclusive pet insurance leads to PX using direct post. We accept POST requests in XML, JSON and HTTP.

Testing

Before leads can be posted into PX’s live environment, tests need to be performed to ensure success. For testing purposes, credentials will be provided by PX.

Testing URL: http://api.open.stagingpx.com/px

Live

Once a lead has been successfully posted and proper posting is confirmed by PX, posting in live can begin. To post into the live environment, PX will provide you with a new set of API credentials.

Live URL: https://secureopenapi.px.com/px

Examples



Post
<?xml version="1.0" encoding="utf-8"?>
<LeadData Target="Lead.Insert" Partner="xxxx" Password="xxxx" RequestTime="2012-12-31 14:58:36" UserAgent="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36" OriginalURL="http://www.exampleURL.com" SessionLength="7" TCPAText="By clicking Get My Quotes, I authorize security companies, their dealers and partner companies to contact me about security offers by phone calls and text messages to the number I provided. I authorize that these marketing communications may be delivered to me using an automatic telephone dialing system or by prerecorded message. I understand that my consent is not a condition of purchase" >
<!-- Your own AffiliateData all values are mandatory except the last 3--> <!-- LeadId can be empty or omitted when not used -->
<AffiliateData Id="72" OfferId="71" SubId="CD1332" Sub2Id="x25" Source="All" VerifyAddress="false" RespondOnNoSale="true" SellResponseURL="" LeadId="" TrustedForm="" ClickConsentID="" />
<ContactData>
        <FirstName>John</FirstName>
        <LastName>Doe</LastName>
        <Address>1 Little West 12th</Address>
        <City>New York</City>
        <State>AL</State> 
        <ZIPCode>10014</ZIPCode>
        <EmailAddress>test@testemail.com</EmailAddress>
        <PhoneNumber>6467171795</PhoneNumber>
        <DayPhoneNumber>6467171795</DayPhoneNumber>
        <IPAddress>255.255.255.255</IPAddress>
</ContactData>
<QuoteRequest QuoteType="Pet">
        <Owners>
                <Owner>
                        <FirstName>John</FirstName>
                        <LastName>Dummy</LastName>
                        <BirthDate>1980-07-14</BirthDate>
                        <Gender>Male</Gender>
                </Owner>
        </Owners>
        <Pets>
                <Pet>
                        <Species>Dog</Species>
                        <SpayedOrNeutered>No</SpayedOrNeutered>
                        <PetName>Bello</PetName>
                        <DogBreed>Affenpinscher</DogBreed>
                        <DogBirthDate>1980-14-07</DogBirthDate>
                        <DogGender>Male</DogGender>
                        <DogConditions>No</DogConditions>
                        <CatBreed>Abyssinian</CatBreed>
                        <CatBirthDate>1980-07-14</CatBirthDate>
                        <CatGender>Male</CatGender>
                        <CatConditions>No</CatConditions>
                </Pet>
        </Pets>
</QuoteRequest>
</LeadData>




Post
{
        "type": "jsonwsp/request",
        "version": "1.0",
        "methodname": "Lead.Insert",
        "LeadData": {
                "Target": "Lead.Insert",
                "Partner": "xxxx",
                "Password": "xxxx",
                "RequestTime": "2012-12-31 14:58:36",
                "UserAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36",
                "OriginalURL": "http://www.exampleURL.com",
                "SessionLength": "7",
                "TCPAText": "By clicking Get My Quotes, I authorize security companies, their dealers and partner companies to contact me about security offers by phone calls and text messages to the number I provided. I authorize that these marketing communications may be delivered to me using an automatic telephone dialing system or by prerecorded message. I understand that my consent is not a condition of purchase",
                "AffiliateData": {
                        "Id": "72",
                        "OfferId": "71",
                        "SubId": "CD1332",
                        "Sub2Id": "x25",
                        "Source": "All",
                        "VerifyAddress": "false",
                        "RespondOnNoSale": "true",
                        "SellResponseURL": "",
                        "LeadId": "",
                        "TrustedForm": "",
                        "ClickConsentID": ""
                },
                "ContactData": {
                        "FirstName": "John",
                        "LastName": "Doe",
                        "Address": "1 Little West 12th",
                        "City": "New York",
                        "State": "AL",
                        "ZIPCode": "10014",
                        "EmailAddress": "test@testemail.com",
                        "PhoneNumber": "6467171795",
                        "DayPhoneNumber": "6467171795",
                        "IPAddress": "255.255.255.255"
                },
                "QuoteRequest": {
                        "QuoteType": "Pet",
                        "Owners": {
                                "Owner": {
                                        "FirstName": "John",
                                        "LastName": "Dummy",
                                        "BirthDate": "1980-07-14",
                                        "Gender": "Male"
                                }
                        },
                        "Pets": {
                                "Pet": {
                                        "Species": "Dog",
                                        "SpayedOrNeutered": "No",
                                        "PetName": "Bello",
                                        "DogBreed": "Affenpinscher",
                                        "DogBirthDate": "1980-14-07",
                                        "DogGender": "Male",
                                        "DogConditions": "No",
                                        "CatBreed": "Abyssinian",
                                        "CatBirthDate": "1980-07-14",
                                        "CatGender": "Male",
                                        "CatConditions": "No"
                                }
                        }
                }
        }
}

XML Fields Table JSON Fields Table HTTP Fields Table


Parameter Required Accepted Values
 Description (data type)
Target Yes “Lead.Insert” String
PartnerToken Yes Provided by PX GUID format
RequestTime No yyyy-MM-dd HH:mm:ss Exact time when lead is generated
UserAgent No String
OriginalURL Yes URL URL where the lead is generated
SessionLength Yes Amount of time spent by user to fill out form in seconds (Integer)
TCPAText Yes Consent language
 String
Id Yes Provided by PX Integer
OfferId Yes Provided by PX Integer
SubId No Format provided at start String
Sub2Id No Discuss with Acc. Manager String
Sub3Id No Discuss with Acc. Manager String
Sub4Id No Discuss with Acc. Manager String
Source Yes Discuss with Acc. Manager String
VerifyAddress No True / False See explanation on this parameter
RespondOnNoSale No True / False See explanation on this parameter
OriginalCreationDate For aged data only yyyy-mm-dd hh:mm:ss String
SellResponseURL No Postback URL See explanation on this parameter
LeadId Yes Jornaya LeadId (GUID format) See link on how to implement on form
TrustedForm No TrustedForm Cert. URL See link on how to implement on form
ClickConsentID No Integer
FirstName Yes String
LastName Yes String
Address Yes String
City Yes String
State Yes See accepted values list
 String
ZIPCode Yes 5 digit zip code
EmailAddress Yes Valid email address String
PhoneNumber Yes Valid 10 digit phone number without formatting 8887777777 Integer
DayPhoneNumber No Valid 10 digit phone number without formatting 8887777777 Integer
IPAddress Yes Example: 38.88.150.2 String
BirthDate No yyyy-mm-dd String
Gender No Male/Female String
CustomField1 No Free text field String
CustomField2 No Free text field String
CustomField3 No Free text field String
CustomField4 No Free text field String
CustomField5 No Free text field String
CustomField6 No Free text field String
CustomField7 No Free text field String
CustomField8 No Free text field String
CustomField9 No Free text field String
CustomField10 No Free text field String
Species Yes Dog / Cat String
SpayedOrNeutered Yes Yes / No String
PetName Yes Free text field String
DogBreed mandatory when Dog See accepted values list String
DogBirthDate mandatory when Dog yyyy-mm-dd String
DogGender mandatory when Dog Male / Female String
DogConditions mandatory when Dog Yes / No String
CatBreed mandatory when Cat See accepted values list String
CatBirthDate mandatory when Cat yyyy-mm-dd String
CatGender mandatory when Cat Male / Female String
CatConditions mandatory when Cat Yes / No String

Parameter Required Accepted Values
 Description (data type)
Target Yes “Lead.Insert” String
PartnerToken Yes Provided by PX GUID format
RequestTime No yyyy-MM-dd HH:mm:ss Exact time when lead is generated
UserAgent No String
OriginalURL Yes URL URL where the lead is generated
SessionLength Yes Amount of time spent by user to fill out form in seconds (Integer)
TCPAText Yes Consent language
 String
Id Yes Provided by PX Integer
OfferId Yes Provided by PX Integer
SubId No Format provided at start String
Sub2Id No Discuss with Acc. Manager String
Sub3Id No Discuss with Acc. Manager String
Sub4Id No Discuss with Acc. Manager String
Source Yes Discuss with Acc. Manager String
VerifyAddress No True / False See explanation on this parameter
RespondOnNoSale No True / False See explanation on this parameter
SellResponseURL No Postback URL See explanation on this parameter
OriginalCreationDate For aged data only yyyy-mm-dd hh:mm:ss String
LeadId Yes Jornaya LeadId (GUID format) See link on how to implement on form
TrustedForm No TrustedForm Cert. URL See link on how to implement on form
ClickConsentID No Integer
FirstName Yes String
LastName Yes String
Address Yes String
City Yes String
State Yes See accepted values list
 String
ZIPCode Yes 5 digit zip code
EmailAddress Yes Valid email address String
PhoneNumber Yes Valid 10 digit phone number without formatting 8887777777 Integer
DayPhoneNumber No Valid 10 digit phone number without formatting 8887777777 Integer
IPAddress Yes Example: 38.88.150.2 String
BirthDate No yyyy-mm-dd String
Gender No Male/Female String
CustomField1 No Free text field String
CustomField2 No Free text field String
CustomField3 No Free text field String
CustomField4 No Free text field String
CustomField5 No Free text field String
CustomField6 No Free text field String
CustomField7 No Free text field String
CustomField8 No Free text field String
CustomField9 No Free text field String
CustomField10 No Free text field String
Species Yes Dog / Cat String
SpayedOrNeutered Yes Yes / No String
PetName Yes Free text field String
DogBreed mandatory when Dog See accepted values list String
DogBirthDate mandatory when Dog yyyy-mm-dd String
DogGender mandatory when Dog Male / Female String
DogConditions mandatory when Dog Yes / No String
CatBreed mandatory when Cat See accepted values list String
CatBirthDate mandatory when Cat yyyy-mm-dd String
CatGender mandatory when Cat Male / Female String
CatConditions mandatory when Cat Yes / No String

Parameter Required Accepted Values
 Description (data type)
Command Yes HTTPPost String
Target Yes “Lead.Insert” String
PartnerToken Yes Provided by PX GUID format
RequestTime No yyyy-MM-dd HH:mm:ss Exact time when lead is generated
UserAgent No String
OriginalURL Yes URL URL where the lead is generated
SessionLength Yes Amount of time spent by user to fill out form in seconds (Integer)
TCPAText Yes Consent language String
AffiliateData.Id Yes Provided by PX Integer
AffiliateData.OfferId Yes Provided by PX Integer
AffiliateData.SubId No Format provided at start String
AffiliateData.Sub2Id No Discuss with Acc. Manager String
AffiliateData.Source Yes Discuss with Acc. Manager String
AffiliateData.VerifyAddress No True / False See explanation on this parameter
AffiliateData.RespondOnNoSale No True / False See explanation on this parameter
AffiliateData.SellResponseURL No Postback URL See explanation on this parameter
AffiliateData.OriginalCreationDate For aged data only yyyy-mm-dd hh:mm:ss String
AffiliateData.LeadId No Jornaya LeadId (GUID format) See link on how to implement on form
AffiliateData.TrustedForm No TrustedForm Cert. Url See link on how to implement on form
AffiliateData.ClickConsentID No Integer
ContactData.FirstName Yes String
ContactData.LastName Yes String
ContactData.Address Yes String
ContactData.City Yes String
ContactData.State Yes See accepted values String
ContactData.ZIPCode Yes 5 digit zip code 10005
ContactData.EmailAddress Yes Valid email address String
ContactData.PhoneNumber Yes Valid 10 digit phone number without formatting 8887777777 Integer
ContactData.DayPhoneNumber No Valid 10 digit phone number without formatting 8887777777 Integer
ContactData.IPAddress Yes Example: 38.88.150.2 String
QuoteRequest.QuoteType Yes Home String
QuoteRequest.CustomField1 No Free text field String
QuoteRequest.CustomField2 No Free text field String
QuoteRequest.CustomField3 No Free text field String
QuoteRequest.CustomField4 No Free text field String
QuoteRequest.CustomField5 No Free text field String
QuoteRequest.CustomField6 No Free text field String
QuoteRequest.CustomField7 No Free text field StringAffiliateData.VerifyAddress
QuoteRequest.CustomField8 No Free text field String
QuoteRequest.CustomField9 No Free text field String
QuoteRequest.CustomField10 No Free text field String
QuoteRequest.Owners.Owner.FirstName
 Yes Free text field String
QuoteRequest.Owners.Owner.LastName Yes Free text field String
QuoteRequest.Owners.Owner.BirthDate No yyyy-mm-dd String
QuoteRequest.Owners.Owner.Gender No Male / Female String
QuoteRequest.Pets.Pet.Species Yes Dog / Cat String
QuoteRequest.Pets.Pet.SpayedOrNeutered Yes Yes / No String
QuoteRequest.Pets.Pet.PetName Yes Free text field String
QuoteRequest.Pets.Pet.DogBreed mandatory when Dog See accepted values list String
QuoteRequest.Pets.Pet.DogBirthDate mandatory when Dog yyyy-mm-dd String
QuoteRequest.Pets.Pet.DogGender mandatory when Dog Male / Female String
QuoteRequest.Pets.Pet.DogConditions mandatory when Dog Yes / No String
QuoteRequest.Pets.Pet.CatBreed mandatory when Cat See accepted values list String
QuoteRequest.Pets.Pet.CatBirthDate mandatory when Cat yyyy-mm-dd String
QuoteRequest.Pets.Pet.CatGender mandatory when Cat Male / Female String
QuoteRequest.Pets.Pet.CatConditions mandatory when Cat Yes / No String

Responses

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

Success


{
"Result": "BaeOK",
"TransactionID": "29D1D8FE-C0A6-4D3B-947A-9FD338CB0646"
}



<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Result Value="BaeOK">
        <TransactionID>B7E8750D-DC8E-4715-A700-C9D1B315224D</TransactionID>
    </Result>
</Response>



{
"Result": "BaeOK",
"TransactionID": "29D1D8FE-C0A6-4D3B-947A-9FD338CB0646"
}

Failures


{
"Result": "BaeNOK",
"Reason": "Mandatory parameter is missing."
}



<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Result Value="BaeNOK">
        <Error>
            <Reason>Mandatory parameter is missing.</Reason>
        </Error>

</Response> 


{
"Result": "BaeNOK",
"Reason": "Mandatory parameter is missing."
}

  • The “Reason” parameter gives a general error code.
  • The “Param” parameter gives the field that causes the error.
  • The “ExtraInfo” contains extra information such as the section.

The table below shows all the failure reasons and the way on how to fix them:

Reason Explanation for failure If not collected, hard code to
Mandatory parameter is missing You’re missing a required field See upper table to find out what is mandatory
Value is not in specified list You’re passing over a not accepted value See upper table to view the accepted values
Duplicate Entry You’re posting a lead with the same ZIPCode within 600 seconds N/A
Partner login failed, API access denied. Your credentials couldn’t be verified by the API Check the Partner and Password or URL encode any % signs (this may cause the API verification to break)
Unable to Monetize Your lead couldn’t be sold to any of the lead buyers Check with your account manager to improve monetization on your leads

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

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.