The Pipl Search APITrack this API allows you to perform people lookups using a variety of search inputs. In this tutorial I will demonstrate how to use the API to enrich the data you have of your newsletter subscribers.
You run a blog or newsletter, and have a newsletter signup form. Like most newsletter signup forms, it only asks for the subscriber’s email address. This means that all you have is your users' email addresses - that's nice, but it doesn't tell you very much about them. To better understand your audience, you want to be able to put a name behind that email address, maybe get a job title, social profile or demographic data such as gender, age, or country of residence.
This is where the Pipl Search API comes in - it allows you to run searches by email address and returns a whole bunch of data about the person behind it.
Pipl API requests are authorized using an API key. For initial testing, you can use sample_key, but that will be limited to 10 calls per IP per day, so you might as well go ahead and open a demo key which is free for testing purposes.
To start off, go ahead and open pipl.com/dev. On the pricing page you'll be able to see a description of all packages and their different features. There are many minor differences between the packages, but I will explain the most important ones:
- The social package is used for social data points only - it's useful if all you're looking for are social network usernames, user IDs, and profile images.
- The packages from power and up include live data providers, which generally means an increased chance of you finding the People you're looking for.
- The premium package involves additional data sets, potentially increasing the likelihood of finding a match. in addition to the normal live data providers, will also pull up data from exclusive datasets, and will provide the absolute best coverage of all the packages.
Once you've made up your mind on the type of package you need, head over to the pricing page and click on "free key". Follow the steps on screen to register your account, and after verifying your email address you will receive a secret key.
During the examples in this tutorial, I will keep using sample_key. Please substitute that for the key you have generated.
The Request/Response Model
The API Endpoint is located at: https://api.pipl.com/search/v4/. You'll note that going to the endpoint directly is not very useful - we’ll need to add some parameters to get something useful out of this, let's add some parameters:
You'll receive a JSON object by opening this URL in your browser. The root element is referred to as the Pipl API Response object. The full specification for this object is available in the API reference: https://pipl.com/dev/reference/#response.
As a convention throughout the Pipl API, metadata fields are prefixed with the `@` symbol, as opposed to real data. Some examples of metadata in the Response object are the "@http_status_code" and "@search_id" properties, which tell you the HTTP response code and the search ID (useful for debugging), respectively.
Moving on to real data, the query object shows your query as a Person object. This lets you examine how your search was interpreted on the API servers, for example how raw fields were parsed.
Now to the exciting stuff: the Person object shows you the actual data you have requested. The Person object is organized into sub-lists of actual data points - for instance a list of addresses, a list of names, a list of jobs, educations and so forth. The entire Person object reference, including all possible data points, is available here: https://pipl.com/dev/reference/#person.