PX Open API Direct Post

Introduction

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

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

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


<?xml version="1.0" encoding="UTF-8"?>
<Lead>
	<ApiToken>xxxx</ApiToken>
	<Vertical>Pet Insurance</Vertical>
	<OriginalUrl>https://google.com</OriginalUrl>
        <SubId>FB1</SubId>
        <Sub2Id></Sub2Id>
        <Sub3Id></Sub3Id>
        <Sub4Id></Sub4Id>
        <Sub5Id></Sub5Id>
	<SellResponseUrl>https://example.com?TransactionId={transactionid}&Payout={payout}&Result={Result}&Reason={Reason}&SubID={subid}</SellResponseUrl>
        <OriginalCreationDate>2022-07-07 12:00:01+02</OriginalCreationDate>
        <ContactData>
		<ZipCode>90170</ZipCode>
		<EmailAddress>test@somedomain.com</EmailAddress>
                <PhoneNumber>6467171795</PhoneNumber>
	</ContactData>
	<Pets>
		<Pet>
			<Species>Dog</Species>
			<PetName>Bello</PetName>
			<DogBreed>Affenpinscher</DogBreed>
			<DogBirthDate>1980-14-07</DogBirthDate>
			<DogGender>Male</DogGender>
			<Species>Cat</Species>
			<PetName>Bella</PetName>
			<CatBreed>Abyssinian</CatBreed>
			<CatBirthDate>1980-14-07</CatBirthDate>
			<CatGender>Female</CatGender>
		</Pet>
	</Pets>
</Lead>


{
	"ApiToken": "xxxx",
	"Vertical": "Pet Insurance",
        "SubId": "FB1",
        "Sub2Id": "",
        "Sub3Id": "",
        "Sub4Id": "",
        "Sub5Id": "",
	"OriginalUrl": "https://google.com",
	"SellResponseUrl": "https://example.com?TransactionId={transactionid}&Payout={payout}&Result={Result}&Reason={Reason}&SubID={subid}",
	"OriginalCreationDate": "2022-07-07 12:00:01+02",
        "ContactData": {
		"ZipCode": "90170",
		"EmailAddress": "test@somedomain.com",
                "PhoneNumber": "6467171795",
	},
	"Pets": {
		"Pet": {
			"Species": "Dog",
			"PetName": "Bello",
			"DogBreed": "Affenpinscher",
			"DogBirthDate": "1980-14-07",
			"DogGender": "Male",
			"Species": "Cat",
			"PetName": "Bella",
			"CatBreed": "Abyssinian",
			"CatBirthDate": "1980-14-07",
			"CatGender": "Female"
		}
	}
}

Fields Table

Parameter	Required	Accepted Values	Description (data type)
ApiToken	Yes	Provided by PX	GUID format
Vertical	Yes	Pet Insurance	String
OriginalURL	Yes	URL where the lead is from	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
SellResponseUrl	No	Postback URL	See explanation on this parameter
OriginalCreationDate	For aged data only	Exact date the aged lead originally has been created: yyyy-mm-dd hh:mm:ssZ	String
ZIPCode	Yes	5 digit zip code
EmailAddress	Yes	Valid email address	String
PhoneNumber	Yes	Valid 10 digit phone number without formatting 8887777777	String
Species	Yes	Dog / Cat	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
CatBreed	mandatory when Cat	See accepted values list	String
CatBirthDate	mandatory when Cat	yyyy-mm-dd	String
CatGender	mandatory when Cat	Male / Female	String

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

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.

DogBreed

Affenpinscher
Afghan Hound
African Boerboel
Ainu Dog
Airedale Terrier
Akbash
Akita
Alaskan Husky
Alaskan Klee Kai
Alaskan Malamute
American Allaunt
American Alsatian
American Barbet
American Bulldog
American Bully
American Cocker Spaniel
American Eskimo Dog
American Foxhound
American Hairless Terrier
American Indian Dog
American Staffordshire Terrier
American Water Spaniel
Anatolian Shepherd Dog
Anglo-french Hounds
Appenzell Mountain Dog
Ariegeois
Armant
Artois Hound
Arubian Cunucu
Atlas Dog
Australian Cattle Dog
Australian Kelpie
Australian Shepherd
Australian Short-haired Pinscher
Australian Silky Terrier
Australian Terrier
Austrian Coarse-haired Hound
Austrian Hound
Auvergne Setter
Azawakh Hound
Balkan Hound
Banjara Greyhound
Barbet
Basenji
Basset Artesien Normand
Basset Griffon Vandeen
Basset Hound
Bavarian Mountain Dog
Beagle
Beagle Harrier
Beagle Mix
Bearded Collie
Beauce Shepherd
Beauceron
Bedlington Terrier
Belgian Malinois
Belgian Sheepdog
Belgian Shepherd
Belgian Shepherd Malinois
Belgian Shepherd Tervuren
Belgian Tervuren
Bergamasco
Berger De Bresse
Berger De Savoie
Berger Du Languedoc
Bernese Hound
Bernese Mountain Dog
Bichon Frise
Bichon Mix
Biewer Terrier
Billy
Black And Tan Coonhound
Black Forest Hound
Black Mouth Cur
Black Russian Terrier
Bloodhound
Blue Heeler
Blue Lacy
Bluetick Coonhound
Boerboel
Bolognese
Border Collie
Border Collie Mix
Border Terrier
Borzoi
Bosnian Coarse-haired Hound
Boston Terrier
Bourbonnais Setter
Bouvier Des Flandres
Boxer
Boxer Mix
Boykin Spaniel
Braque Du Bourbonnais
Brazilian Guard Dog
Brazilian Tracker
Briard
Briquet Griffon Vendeen
Brittany
Broholmer
Brussels Griffon
Bugg
Bull Terrier
Bulldog
Bulldog Mix
Bullmastiff
Bulloxer
Cairn Terrier
Canaan Dog
Canadian Husky
Cane Corso
Cardigan Corgis
Cardigan Welsh Corgi
Carolina Dog
Catahoula Leopard
Catalonian Shepherd
Caucasian Ovcharka
Cavachon
Cavalier King Charles Spaniel
Cavapoo
Cesky Terrier
Charplaninatz
Chesapeake Bay Retriever
Chihuahua
Chihuahua Mix
Chinese Crested Dog
Chinese Imperial
Chinook
Chiweenie
Chow Chow
Chow Mix
Chug
Clumber Spaniel
Cockapoo
Cocker Spaniel
Collie
Coon Hound
Corgi Mix
Coton De Tulear
Curly-Coated Retriever
Czech Coarse-haired Setter
Czech Shepherd
Dachsbrackes
Dachshund
Dachsund Mix
Dalmatian
Dalmatian Mix
Dandie Dinmont Terrier
Danish-Swedish Farm
Deerhound
Deutsche Wachtelhund
Dingo
Doberman
Dogo Argentino
Dogue De Bordeaux
Drentse Partridge Dog
Drever
Dunker
Dupuy Setter
Dutch Shepherd
Elkhound
English Bull Terrier
English Bulldog
English Cocker Spaniel
English Coonhound
English Foxhound
English Mastiff
English Retriever
English Setter
English Shepherd
English Springer Spaniel
English Toy Spaniel
English Toy Terrier
Entlebuch Mountain Dog
Eskimo Dog
Estonian Hound
Estrela Mountain Dog
Eurasier
Feist
Fell Terrier
Field Spaniel
Fila Brasileiro
Finnish Hound
Finnish Lapphund
Finnish Spitz
Flat-coated Retriever
Fox Terrier
French Bulldog
French Hounds
French Setter
French Spaniel
Frenchton
Gascons-saintongeois
German Hunt Terrier
German Pinscher
German Shepherd
German Shorthaired Pointer
German Spaniel
German Spitz
German Wirehaired Pointer
Giant Schnauzer
Glen Of Imaal Terrier
Golden Retriever
Goldendoodle
Gordon Setter
Grand Gascons-Saintongeois
Grand Griffon Vandeen
Great Bernese
Great Dane
Great Gascony Blue
Great Pyrenees
Greater Swiss Mountain Dog
Greenland Dog
Greyhound
Haldenstovare
Hamiltonstovare
Hanover Hound
Harlequin Pinscher
Harrier
Havanese
Hellenic Hound
Hound Mix
Hovawart
Hungarian Coarse-Haired Vizsla
Hungarian Greyhound
Hungarian Kuvasz
Hungarian Puli
Hungarian Vizsla
Husky
Hygenhund
Ibizan Hound
Ibizan Wolfhound
Iceland Sheepdog
Irish Red & White Setter
Irish Red Setter
Irish Setter
Irish Terrier
Irish Water Spaniel
Irish Wolfhound
Istrian Hounds
Italian Greyhound
Italian Mastiff
Italian Segugio
Italian Setter
Italian Spinone
Italian Spitz
Jack Russell Terrier
Jamthund
Japanese Akita
Japanese Chin
Japanese Fighting Dog
Japanese Kai Ken
Japanese Kishu
Japanese Spitz
Japanese Terrier
Jindo
Jura Hounds
Kangal Dog
Kangaroo Hound
Karelian Bear Dog
Karst Shepherd
Keeshond
Kerry Blue Terrier
King Charles Spaniel
King Shepherd
Komondor
Kooikerhondje
Kromfohrlander
Kuvasz
Labradoodle
Labrador Mix
Labrador Retriever
Lagotto Romagmolo
Laikas
Lakeland Terrier
Lancashire Heeler
Lapland Spitz
Lapponian Herder
Large Munsterlander
Leonberger
Levesque
Lhasa Apso
Lhasa Apso Mix
Llewellin Setter
Lowchen
Lucernese Hound
Lundehund
Lurcher
Majestic Tree Hound
Majorcan Bulldog
Maltese
Malti-Poo
Manchester Terrier
Maremma Sheepdog
Mastiff
Mastiff Mix
McNab
Mexican Hairless Dog
MI-KI
Miniature American Eskimo
Miniature Australian Shepherd
Miniature Bull Terrier
Miniature Dachshund
Miniature English Bulldog
Miniature Husky
Miniature Pinscher
Miniature Poodle
Miniature Pug
Miniature Schnauzer
Miniature Spitz
Miniature Yorkie
Mixed Dog
Morkie
Mountain Cur
Mountain Feist
Mudi
Native American Indian Dog
Neopolitan Mastiff
New Guinea Singing Dog
Newfoundland
Nivernais Griffon
Norfolk Terrier
Norrbottenspets
Norwegian Buhund
Norwegian Elkhound
Norwegian Lundehund
Norwich Terrier
Nova Scotia Duck Tolling Retriever
Oeruvian Inca Orchid
Old Danish Pointer
Old English Sheepdog
Olde Boston Bulldogge
Olde English Bulldogge
Otterhound
Ovcharka
Papillon
Parson Jack Russell Terrier
Patterdale Terrier
Peekapoo
Pekingese
Pembroke Welsh Corgi
Peruvian Inca Orchid
Petit Basset Griffon Vendeen
Petit Brabancon
Pharaoh Hound
Picardy Shepherd
Pinscher
Pit Bull
Pit Bull Mix
Plott Hound
Poggle
Pointer
Pointer Mix
Poitevin
Polish Lowland Sheepdog
Pom-Poo
Pomeranian
Pomeranian Mix
Pont-audemer Spaniel
Poodle
Poodle (Standard)
Poodle Mix
Porcelaine
Portuguese Podengo
Portuguese Setter
Portuguese Sheepdog
Portuguese Watchdog
Portuguese Water Dog
Posavatz Hound
Prague Ratter
Presa Canario
Pudelpointer
Pug
Pug Mix
Puggle
Pugshire
Puli
Pumi
Pyrenean Mastiff
Pyrenean Mountain Dog
Pyrenean Shepherd
Queensland Heeler
Rafeiro Do Alentejo
Rat Terrier
Redbone Coonhound
Redtick Coonhound
Retriever Mix
Rhodesian Ridgeback
Rottweiler
Rottweiler Mix
Rough Collie
Rumanian Shepherd Dog
Russian Hounds
Russian Sheepdogs
Russian Toy Terrier
Russian Tsvetnaya Bolonka
Saint Bernard
Saint-German Setter
Saluki
Samoyed
Schapendoes
Schiller Hound
Schipperke
Schnauzer (Standard)
Schnauzer Mix
Schnoodle
Scottish Deerhound
Scottish Terrier
Sealyham Terrier
Shar-pei
Shar-pei Mix
Sheltie
Sheltie Mix
Shepherd Mix
Shetland Sheepdog
Shiba Inu
Shih Tzu
Shih Tzu Mix
Shih-Poo
Shiloh Shepherd
Siberian Husky
Sicilian Hound
Silken Windhound
Silky Terrier
Skye Terrier
Sloughi
Slovakian Kuvasz
Sluki
Smaland Hound
Small Blue Gascony Griffon
Small Gascons-Saintongeois
Small Gascony Blue
Small Munsterlanders
Small-sized French Setter
Smooth Collie
Smooth Fox Terrier
Soft Coated Wheaten Terrier
Spanish Alano
Spanish Greyhound
Spanish Hounds
Spanish Mastiff
Spanish Pointer
Spanish Water Dog
Spinone Italiano
Spitz
Springer Spaniel
Stabyhoun
Staffordshire Bull Terrier
Staffordshire Terrier
Steinbracke
Stephens` Stock
Sussex Spaniel
Swedish Grey Dog
Swedish Lapphund
Swedish Vallhund
Swiss Hound
Tahltan Bear Dog
Tamaskan
Tawny Brittany Basset
Tawny Brittany Griffon
Teacup Poodle
Teacup Yorkie
Telomian
Terrier Mix
Thai Ridgeback
Tibetan Mastiff
Tibetan Spaniel
Tibetan Terrier
Tosa Inu
Toy Australian Shepherd
Toy Fox Terrier
Toy Maltese
Toy Manchester Terrier
Toy Poodle
Translvanian Hound
Treeing Tennessee Brindle
Tyrolean Hound
Victorian Bulldog
Vizsla
Walker Hound
Weimaraner
Welsh Corgi
Welsh Springer Spaniel
Welsh Terrier
West Highland Terrier
West Highland White Terrier
Wetterhound
Wheaten Terrier
Whippet
Wire Fox Terrier
Wirehaired Pointing Griffon
Wooly-Haired Griffon
Yellow Lab
Yorkie Mix
Yorkie Poo
Yorkshire Terrier
Yugoslavian Mountain Dog

CatBreed

Abyssinian
Alley Cat
American Bobtail
American Curl
American Curl Shorthair
American Longhair
American Shorthair
American Wirehair
Angora
Balinese
Bengal
Bengalese
Birman
Bombay
British Shorthair
Burmese
Burmilla
Calico
California Spangled
Cameo Longhair
Chartreux
Chausie
Chinchilla
Colorpoint
Colorpoint Longhair
Colorpoint Shorthair
Cornish Rex
Cymric
Devon Rex
Domestic Longhair
Domestic Mediumhair
Domestic Shorthair
Dwarf Cat
Egyptian Mau
European Burmese
European Shorthair
Exotic
Exotic Longhair
Exotic Shorthair
Havana Brown
Highland Fold
Highland Lynx Cat
Himalayan
Himalayan Blue Point
Himalayan Flame Point
Himalayan Lilac Point
Himalayan Seal Point
Japanese Bobtail
Kashmir
Korat
LaPerm
Maine Coon
Manx
Minskin
Mixed Cat
Moggie
Munchkin
Nibelung
Norwegian Forest
Ocicat
Oriental
Oriental Colorpoint
Oriental Longhair
Oriental Shorthair
Persian
Pixie Bob
Ragamuffin
Ragdoll
Russian Blue
Savannah
Scottish Fold
Scottish Fold Longhair
Selkirk Rex
Selkirk Rex Longhair
Seychellois
Siamese
Siberian
Singapura
Snowshoe
Somali
Sphynx
Tabby
Tiffanie
Tonkinese
Turkish Angora
Turkish Van

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}

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

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

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