API Reference
HomeMy Account

Search Query Parameters

Query Parameters

Use any combination of the parameters below. Each parameter may be used only once. A search request has to contain at least one valid name, email address, phone, username, user id, URL, or a full US address (including a house number).

ParameterExampleDescription
email[email protected]Email address
phone+1 (978) 555-0145Home/work/mobile phone number. We’ll try to parse the number using libphonenumber.
usernamesupermanUsername/screen-name, minimum 3 characters. There’s an advanced option to search by username or user-id at a specific service like superman@facebook.
user_id11231@facebookUnique ID in a supported service. It must include the service name.
urlhttps://www.linkedin.com/pub/superman/20/7a/365Profile URL in a supported service. This URL will be parsed to a username or user_id object.
first_nameClarkFirst name, minimum 2 characters, except when using a partial name search.
last_nameKentLast name, minimum 2 characters, except when using a partial name search.
middle_nameJosephMiddle name or middle initial
raw_nameClark Joseph KentFull Name. Use this parameter if the accurate name parts (first/middle/last) are not available. This parameter will only be used in absence of first_name and last_name.
countryUSA two-letter, Alpha-2 ISO-3166 country code.
stateKSA United States, Canada, Great Britain or Australia state code. If a US state is provided and no country specified, we’ll assume the country to be US.
citySmallvilleCity
streetHickory LaneStreet
house10House number
zipcode66605ZIP Code
raw_address10-1 Hickory Lane, Smallville, KansasFull address. Use this parameter if the accurate address parts (country/state/city…) are not available.
vin
coming soon		1ftrx18wx2nb71717Vehicle identifier number
age26-29String, an exact (YY) or approximate (YY-YY) age.

Example

https://api.pipl.com/search/[email protected]&key=YOURKEY

from piplapis.search import SearchAPIRequest
request = SearchAPIRequest(email='[email protected]', api_key='YOURKEY')
response = request.send()

require 'pipl'
response = Pipl::client.search email: '[email protected]', api_key: 'YOURKEY'

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

SearchAPIConfiguration configuration = new SearchConfiguration();
configuration.apiKey = 'YOURKEY'

SearchAPIRequest request = new SearchAPIRequest.Builder()
                                               .email("[email protected]")
  																						 .configuration(configuration)
                                               .build();
SearchAPIResponse response = request.send();

<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->api_key = 'YOURKEY';
  
$request = new PiplApi_SearchAPIRequest(array('email' => '[email protected]',
'first_name' => 'Clark',
'last_name' => 'Kent'), $configuration);
$response = $request->send();

using Pipl.APIs.Search;

SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY");
SearchAPIRequest request = new SearchAPIRequest(email: "[email protected]",
firstName: "Clark",
lastName: "Kent", requestConfiguration: searchConfiguration);
SearchAPIResponse response = await request.SendAsync();

curl https://api.pipl.com/search/\[email protected]\&key=YOURKEY

Common Search Types

The Pipl Search API lets you search by many different data points and combinations of data points. As long as you meet the minimum search criteria, you can craft a variety of different queries to find information on a person. This flexibility allows Pipl Search to fit a large variety of workflows and use-cases. In general, the more data you are able to provide in the query, the better results you will get. Below are some of the most common search types that we see get strong results when using the Search API. This list is not exhaustive, but meant to give you a recommendation for a strong starting point: