Search Using Full Person
Full Person Searches
While searching using the parameters list is straightforward, it is not enough for advanced searches.
The person search allows you to search with multiple data fields of the same type and by components that are not available in the basic search parameters search including job, education, gender and relationship. Please note that all attribute names should be lowercase.
Let’s say, for example, you want to search for a person for which you have two addresses: Metropolis, KS and Smallville, KS, Using the simple search, you can’t do that.
For this kind of situation, we allow you to search by a full person object. If you are using one of the client libraries, then build a person object and pass it to the request. Otherwise you need to send a url-encoded JSON string of the person you are looking for.
👍 Rule of thumb
The more data you bring in, the better results you get.
Examples
Say for example we wish to send a Person object with 1 email address and 2 addresses.
{
"emails": [{
"address": "clark.kent@example.com"
}],
"addresses": [{
"country": "US",
"state": "KS",
"city": "Metropolis"
}, {
"country": "US",
"state": "KS",
"city": "Smallville"
}]
}
Example request
- HTTPS
- Python
- Ruby
- Java
- PHP
- C#
- cURL
https://api.pipl.com/search/?person={"emails":[{"address": "clark.kent@example.com"}],"addresses":[{"country":"US", "state": "KS", "city": "Metropolis"},{"country":"US", "state": "KS", "city": "Smallville"}]}&key=YOURKEY
from piplapis.search import SearchAPIRequest
from piplapis.data import Person
from piplapis.data.fields import Address, Email
person = Person()
person.emails.append(Email("clark.kent@example.com"))
person.addresses.extend([Address(city="Metropolis", country="US", state="KS"),
Address(city="Smallville", country="US", state="KS")])
request = SearchAPIRequest(person=person, api_key='YOURKEY')
response = request.send()
require 'pipl'
person = Pipl::Person.new
person.add_field Pipl::Name.new(first: 'Clark', last: 'Kent')
person.add_field Pipl::Address.new(country: 'US', state: 'KS', city: 'Smallville')
person.add_field Pipl::Address.new(country: 'US', state: 'KS', city: 'Metropolis')
response = Pipl::client.search person: person, api_key: 'YOURKEY'
import java.util.ArrayList;
import java.util.List;
import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchConfiguration;
import com.pipl.api.data.containers.Person;
import com.pipl.api.data.fields.*;
SearchAPIConfiguration configuration = new SearchConfiguration();
configuration.apiKey = 'YOURKEY'
ListField fields = new ArrayListField();
fields.add(new Name.Builder().first("Clark").last("Kent").build());
fields.add(new Address.Builder().country("US").state("KS").city("Smallville").build());
fields.add(new Address.Builder().country("US").state("KS").city("Metropolis").build());
fields.add(new Job.Builder().title("Field Reporter").build());
Person person = new Person(fields);
SearchAPIRequest request = new SearchAPIRequest(person, configuration);
SearchAPIResponse response = request.send()
<?php
require_once './piplapis/search.php';
$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->api_key = 'YOURKEY';
$fields = array(new PiplApi_Address(array("country" => "US", "state" => "KS", "city" => "Metropolis")),
new PiplApi_Address(array("country" => "US", "state" => "KS", "city" => "Smallville")),
new PiplApi_Name(array("first" => "Clark", "middle" => "Joseph", "last" => "Kent")),
new PiplApi_Job(array("title" => "Field Reporter")),
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), $configuration);
$response = $request->send();
using Pipl.APIs.Data.Containers;
using Pipl.APIs.Data.Fields;
using Pipl.APIs.Search;
SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY");
var fields = new ListField()
{
new Name(first: "Clark", last: "Kent"),
new Address(country: "US", state: "KS", city:"Smallville"),
new Address(country: "US", state: "KS", city:"Metropolis"),
new Job(title: "Field Reporter")
};
Person person = new Person(fields);
var request = new SearchAPIRequest(person: person, requestConfiguration: configuration);
var response = request.SendAsync().Result;
curl https://api.pipl.com/search/ \
-d person='{"emails":[{"address": "clark.kent@example.com"}],"addresses":[{"country":"US", "state": "KS", "city": "Metropolis"},{"country":"US", "state": "KS", "city": "Smallville"}]}' \
-d key=YOURKEY
Example response
{
"@http_status_code": 200,
"@visible_sources": 2,
"@available_sources": 2,
"@persons_count": 1,
"@search_id": "0",
"query": {
"emails": [
{
"address": "clark.kent@example.com",
"address_md5": "2610ee49440fe757e3cc4e46e5b40819"
}
],
"addresses": [
{
"country": "US",
"state": "KS",
"city": "Metropolis",
"display": "Metropolis, Kansas"
},
{
"country": "US",
"state": "KS",
"city": "Smallville",
"display": "Smallville, Kansas"
}
]
},
"available_data": {
"premium": {
"jobs": 1,
"addresses": 2,
"phones": 1,
"landline_phones": 1,
"educations": 1,
"social_profiles": 2,
"names": 2,
"dobs": 1,
"images": 1,
"genders": 1,
"emails": 1
}
},
"person": {
"@id": "f10e8171-6caa-4c45-9553-f14122c762e7",
"names": [
{
"first": "Clark",
"middle": "Joseph",
"last": "Kent",
"display": "Clark Joseph Kent"
},
{
"first": "Kal",
"last": "El",
"display": "Kal El"
}
],
"emails": [
{
"address": "clark.kent@example.com",
"address_md5": "2610ee49440fe757e3cc4e46e5b40819"
}
],
"phones": [
{
"@type": "home_phone",
"country_code": "1",
"number": "9785550145",
"display": "(978) 555-0145",
"display_international": "+1 978-555-0145"
}
],
"gender": {
"content": "male"
},
"dob": {
"date_range": {
"start": "1986-01-01",
"end": "1987-05-13"
},
"display": "28 years old"
},
"addresses": [
{
"country": "US",
"state": "KS",
"city": "Smallville",
"street": "Hickory Lane",
"house": "10",
"apartment": "1",
"zip_code": "66605",
"display": "10-1 Hickory Lane, Smallville, Kansas"
},
{
"@type": "work",
"country": "US",
"state": "KS",
"city": "Metropolis",
"street": "Broadway",
"house": "1000",
"apartment": "355",
"display": "1000-355 Broadway, Metropolis, Kansas"
}
],
"jobs": [
{
"title": "Field Reporter",
"organization": "The Daily Planet",
"industry": "Journalism",
"date_range": {
"start": "2000-12-08",
"end": "2012-10-09"
},
"display": "Field Reporter at The Daily Planet (2000-2012)"
}
],
"educations": [
{
"degree": "B.Sc Advanced Science",
"school": "Metropolis University",
"date_range": {
"start": "2005-09-01",
"end": "2008-05-14"
},
"display": "B.Sc Advanced Science from Metropolis University (2005-2008)"
}
],
"images": [
{
"url": "http://vignette1.wikia.nocookie.net/smallville/images/e/ea/Buddies_forever.jpg",
"thumbnail_token": "AE2861B242686E7BD0CB4D9049298EB7D18FEF66D950E8AB78BCD3F484345CE74536C19A85D0BA3D32DC9E7D1878CD4D341254E7AD129255C6983E6E154C4530A0DAAF665EA325FC0206F8B1D7E0B6B7AD9EBF71FCF610D57D"
}
],
"urls": [
{
"@domain": "linkedin.com",
"@category": "professional_and_business",
"url": "https://www.linkedin.com/pub/superman/20/7a/365"
},
{
"@domain": "facebook.com",
"@category": "personal_profiles",
"url": "https://www.facebook.com/superman"
}
]
}
}