First Steps

1. Get an API key

All API calls must include a valid API key. This is our way of identifying you and authorizing your call.

If you have an account, you can choose a key on your API Keys page.

To experiment with our API and try a few calls, use the demo page or try out the Postman collection.

2. Choose your code library

Integrating to an API should be easy. We've written code libraries for major programming languages to make integration a breeze. Choose your preferred language. We currently support Python, Ruby, Java, C# and PHP.

Download a code library here

3. Run a "Hello World" query

When you query Pipl, simply enter the information you have about someone and we'll deliver all of the data available about that person.
Let's say we're looking for Clark Kent, who's using the email clark.kent@example.com:

https://api.pipl.com/search/?first_name=Clark&last_name=Kent&email=clark.kent@example.com&key=YOURKEY

📘 Free query

Any query that contains the email address clark.kent@example.com will not be charged and it will provide static example output as a result.

👍 Use Encryption

We require SSL—change any URL prefix to HTTPS instead of HTTP.
API Endpoint: https://api.pipl.com/search/

HTTPS

https://api.pipl.com/search/?email=clark.kent@example.com&key=YOURKEY

Python

#imports
from piplapis.search import SearchAPIRequest

#run search (request/response)
request = SearchAPIRequest(email=u'clark.kent@example.com',
first_name=u'Clark', last_name=u'Kent', api_key='YOURKEY')
response = request.send()

#print portion of response
if response.person:   #Has data so single Full Person response
    currentPerson = response.person
    print("Hello World:")
    print("Number of Names:", len(currentPerson.names))
    print("Name(s):" + "\n" .join(map(str, currentPerson.names)))
    print("Username(s):"  + "\n" .join(map(str, currentPerson.usernames)))
    print("Emails(s):"  + "\n" .join(map(str, currentPerson.emails)))
    print("\n")

Ruby

require 'pipl'
response = Pipl::client.search email: 'clark.kent@example.com', first_name: 'Clark',
last_name: 'Kent', api_key: 'YOURKEY'

Java

import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchAPIResponse;
import com.pipl.api.search.SearchConfiguration;

SearchAPIConfiguration configuration = new SearchConfiguration();
configuration.setProtocol("https");
configuration.apiKey = 'YOURKEY'
SearchAPIRequest request = new
SearchAPIRequest.Builder().email("clark.kent@example.com").firstName("Clark").lastName("Kent").configuration(configuration).build();
SearchAPIResponse response = request.send();

PHP

<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->api_key = 'YOURKEY';
$configuration->use_https = true;

$request = new PiplApi_SearchAPIRequest(array('email' => 'clark.kent@example.com',
'first_name' => 'Clark',
'last_name' => 'Kent'), $configuration);
$response = $request->send();

?>

C#

using Pipl.APIs.Search;
SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY",url: "api.pipl.com/search/", useHttps: true);
SearchAPIRequest request = new SearchAPIRequest(email: "clark.kent@example.com",
firstName: "Clark",
lastName: "Kent", requestConfiguration: searchConfiguration);
SearchAPIResponse response = await request.SendAsync();

Shell

curl https://api.pipl.com/search/\?email=clark.kent@example.com\&key=YOURKEY

You can query with email addresses, phone numbers, usernames, names, addresses, age, or other attributes. Please review the full API reference.

4. Work with the results

When your search is unique—such as entering an email address, social profile, or a very unique name—the search response will contain a single person object. This indicates that we've confidently matched your search parameters to a single, real-world person. The response will look like this:

{
    ...
    "person": {a person object},
    ...
}

If we cannot match your search to a single person, the response will contain a list of possible persons. This can happen if, for example, you searched for a common name such as John Smith.

This list of people will be prioritized and ordered in descending order by a @match score, representing the confidence level that each result is the person you're looking for.

{
    ...
    "possible_persons":
        [{a person object},
         {a person object},
         ... ,
         {a person object}
        ],
    ...
}

The person objects in the response hold the actual data fields.

5. Learn More!

The API Reference is the best resource for learning about using the Pipl Search API.

The Pipl Search API Integration Checklist walks through the steps and tips for integrating the Pipl Search API

The Pipl Search Basic Workflow Diagram shows a simple coding workflow using the Pipl Search API.