Searching by Names

Introduction

Names are the most common data field used in a Pipl Search query. However, they are also a common source of API errors, especially when used alone without any other data fields. Incorrectly formatted names may be parsed incorrectly leading to erroneous results and API warnings. This guide gathers some of the best practices on how to use names in your Pipl Search API queries.

You can send a name to Pipl Search in one of two ways:

• The first name, middle name/initial and last name, all in separate fields
• A single raw name field which will be automatically parsed into the first, middle name/initial and last name fields

Examples

Text

//Using parsed name fields
first_name=Clark&middle_name=Joseph&last_name=Kent

//Using raw name field
raw_name=Clark Joseph Kent

URL

//Using parsed name fields
https://api.pipl.com/search/?key=YOUR-API-KEY&first_name=Clark&middle_name=Joseph&last_name=Kent

//Using raw name field
https://api.pipl.com/search/?key=YOUR-API-KEY&raw_name=Clark Joseph Kent

Python

from piplapis.data import Person, Name
from piplapis.search import SearchAPIRequest

#Using parsed name fields
fields = [Name(first='Clark', middle='Joseph', last='Kent')]
request = SearchAPIRequest(person=Person(fields=fields), api_key='YOUR-API-KEY')
response = request.send()

#Using raw name field (direct parameter)
request = SearchAPIRequest(raw_name='Clark Joseph Kent', api_key='YOUR-API-KEY')
response = request.send()

#Using raw name field (in Person object)
fields = [Name(raw='Clark Joseph Kent')]
request = SearchAPIRequest(person=Person(fields=fields), api_key='YOUR-API-KEY')
response = request.send()

Ruby

require 'pipl'

#Using parsed name fields
person = Pipl::Person.new
person.add_field Pipl::Name.new(first: 'Clark', middle: 'Joseph', last: 'Kent')
response = Pipl::client.search person: person, api_key: 'YOUR-API-KEY'

#Using raw name field (direct parameter)
response = Pipl::client.search raw_name: 'Clark Joseph Kent', api_key: 'YOUR-API-KEY'

#Using raw name field (in Person object)
person = Pipl::Person.new
person.add_field Pipl::Name.new(raw: 'Clark Joseph Kent')
response = Pipl::client.search person: person, api_key: 'YOUR-API-KEY'

Java

import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchAPIResponse;
import com.pipl.api.data.containers.Person;
import com.pipl.api.data.fields.*;
import com.pipl.api.search.SearchConfiguration;
import java.util.ArrayList;
import java.util.List;

SearchConfiguration configuration = new SearchConfiguration();
configuration.setProtocol("https");
configuration.apiKey = "YOUR-API-KEY";

//Using parsed name fields
List<Field> fields = new ArrayList<Field>();
fields.add(new Name.Builder().first("Clark").middle("Joseph").last("Kent").build());
Person person = new Person(fields);
SearchAPIRequest request = new SearchAPIRequest(person, configuration);
SearchAPIResponse response = request.send();

//Using raw name field (direct parameter)
request = new SearchAPIRequest.Builder()
    .rawName("Clark Joseph Kent")
    .configuration(configuration)
    .build();
response = request.send();

//Using raw name field (in Person object)
fields = new ArrayList<Field>();
fields.add(new Name.Builder().raw("Clark Joseph Kent").build());
person = new Person(fields);
request = new SearchAPIRequest(person, configuration);
response = request.send();

PHP

<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->use_https = true;
$configuration->api_key = 'YOUR-API-KEY';

//Using parsed name fields
$fields = array(
    new PiplApi_Name(array("first" => "Clark", "middle" => "Joseph", "last" => "Kent"))
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), $configuration);
$response = $request->send();

//Using raw name field (direct parameter)
$request = new PiplApi_SearchAPIRequest(
    array('raw_name' => 'Clark Joseph Kent'),
    $configuration
);
$response = $request->send();

//Using raw name field (in Person object)
$fields = array(
    new PiplApi_Name(array("raw" => "Clark Joseph Kent"))
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), $configuration);
$response = $request->send();

?>

C#

using Pipl.APIs.Search;
using System.Collections.Generic;

SearchConfiguration searchConfiguration = new SearchConfiguration(
    apiKey: "YOUR-API-KEY",
    url: "api.pipl.com/search/",
    useHttps: true
);

//Using parsed name fields
List<Field> fields = new List<Field>()
{
    new Name(first: "Clark", middle: "Joseph", last: "Kent")
};
var person = new Person(fields);
SearchAPIRequest request = new SearchAPIRequest(
    person: person,
    requestConfiguration: searchConfiguration
);
var response = await request.SendAsync();

//Using raw name field (direct parameter)
request = new SearchAPIRequest(
    rawName: "Clark Joseph Kent",
    requestConfiguration: searchConfiguration
);
response = await request.SendAsync();

//Using raw name field (in Person object)
fields = new List<Field>()
{
    new Name(raw: "Clark Joseph Kent")
};
person = new Person(fields);
request = new SearchAPIRequest(
    person: person,
    requestConfiguration: searchConfiguration
);
response = await request.SendAsync();

Basic Rules for Names

The basic rules regarding names in the Pipl API, and the validation thereof are as follows:

• When searched alone, names must include a first and last name. Because of Pipl’s worldwide index, a name alone will likely return many Possible Persons - especially if a name is very common. It is best practice to include other searchable fields such as a high-level address (e.g. with country and/or state and/or city) when available with a name to help narrow down the results.
• Both the first name and the last name must be at least 2 characters in length.
  ** These conditions are relaxed with partial name searches as long as the minimum search requirements are met by adding other searchable fields
• The middle name can be 1 or more characters in length. Initials are allowed with or without a dot suffix.
• The first, middle or last fields can include multiple names. These can be separated by spaces, or by a dash/hyphen (i.e double-barrel names).
• “Double-barrel” or “Triple-barrel” names should be sent using a dash/hyphen between the names (e.g. Van-Der-Bank)
• It is suggested to also try alternatives such as VanDerBank
• Foreign characters and special characters can be used for a search should they meet the minimum character length requirements. They will be parsed as UTF-8 encoded strings.
• Company names should not be used (the technology is used to search for a person), but they can be included as a job .
• Don’t include two people’s names in one, the identity resolution technology is used to find a single person

How raw names are parsed

Pipl recommends sending the name parsed into the first, middle and last parts to dismiss any doubt as to how the name should be parsed. However in some cases, you might not have the name separated into first, middle and last, and would need to send the name in a single field to have the Pipl API parse out the name parts for you automatically. Sending the full name in a single field can be done by using the ‘raw’ name field in a Person request or raw_name in a search parameter request.

The “query” section of a Pipl Search API response shows how the API interpreted all the query fields sent to it including how raw names were parsed.

The parsing of names is straightforward for simple names that include first, middle and last name, all as a single string such as “Clark Joseph Kent” or “Clark J Kent”.

Example 1. Taking for example the name “Clark Joseph Kent”, the API parses names from the raw field in the following manner:

Name Component	Detail	Example Parsed	Example Result
First name	The first string token, up to the first space character	Clark Joseph Kent	Clark
Last Name	The last string token, from the last space character	Clark Joseph Kent	Kent
Middle Name	Anything between the first string token and the last string token ( excluding the first and last space characters)	Clark Joseph Kent	Joseph

Example 2. Taking for example a name with a comma such as “Kent, Clark Joseph”, the API parses names from the raw field in the following manner:

Name Component	Detail	Example Parsed	Example Result
First Name	The first string token after the comma	Kent, Clark Joseph	Clark
Last name	The first string token before the comma	Kent, Clark Joseph	Kent
Middle name	All string tokens after the first string token	Kent, Clark Joseph	Joseph

📘 How are names searched on Pipl?

When sending names in raw_name, the search engine, although parsing the name as described above, might attempt, in some cases, to switch first name and last name in order to find the person you are seeking. This might happen when the last name is a common first name, for example Jackson Curtis (parses to Curtis Jackson), Ryan Phillip (parses to Phillip Ryan).

The search engine will recognize some surnames with more than one word (ie “De La Rocha” or “Von Welsbach”) and preserve them as the last name it extracts from a raw_name search. Due to the near infinite number of possible surnames this process is not perfect, but should hold for most compound surnames.

Examples of raw name parsing

The following valid raw names illustrate how titles and names consisting of more than 3 words are parsed.

Raw Name	Parsed First Name	Parsed Middle Name	Parsed Last Name
Clark Joseph Kent	Clark	Joseph	Kent
Clark J Kent	Clark	J	Kent
Ramon Antonio Gerard Estevez	Ramon	Antonio Gerard	Estevez
Daniel Michael Blake Day-Lewis	Daniel	Michael Blake	Day-Lewis
Dr. Victor Frankenstein*	Victor		Frankenstein
Professor Albert Einstein*	Albert		Einstein
Robert Downey Jr.**	Robert		Downey
Dench, Judi	Judi		Dench
David Larry	Larry		David
Zach De La Rocha	Zach		De La Rocha
Zacarias Manuel De La Rocha	Zacarias	Manuel	De La Rocha
Jorge Dos Santos	Jorge		Dos Santos

• Pipl will parse the title to the sub-field ‘prefix’
  ** Pipl will parse the suffix to the sub-field ‘suffix’

The following are examples of invalid names, unless searched as a partial name with additional search parameters included in the search.

Raw Name	Error/Issue
C Kent	First name does not contain 2 characters. *
Clark K.	Last name does not contain 2 characters. *
Dr. Frankenstein	“Dr.” will be parsed as a first name. *
R. Downey Jr.	First name does not contain 2 characters. *

• Cannot be searched alone, is however a valid partial name

Partial name searches

Partial name searches in Pipl Search allow you to search with a portion of the name if the minimum query requirements have already been met with an additional field such as an email, phone or username.

First	Middle	Last	Additional Data Field in Query
J			phone
		Frankenstein	email
Patrick			username

Examples

Text

//Example 1: First name only with phone
first_name=J&phone=+15551234567

//Example 2: Last name only with email
last_name=Frankenstein&email=victor.frankenstein@example.com

//Example 3: First name only with username
first_name=Patrick&username=patrick@twitter

URL

//Example 1: First name only with phone
https://api.pipl.com/search/?key=YOUR-API-KEY&first_name=J&phone=+15551234567

//Example 2: Last name only with email
https://api.pipl.com/search/?key=YOUR-API-KEY&last_name=Frankenstein&email=victor.frankenstein@example.com

//Example 3: First name only with username
https://api.pipl.com/search/?key=YOUR-API-KEY&first_name=Patrick&username=patrick@twitter

Python

from piplapis.data import Person, Name, Email, Phone
from piplapis.search import SearchAPIRequest

#Example 1: First name only with phone
fields = [Name(first='J'), Phone(raw='+15551234567')]
request = SearchAPIRequest(person=Person(fields=fields), api_key='YOUR-API-KEY')
response = request.send()

#Example 2: Last name only with email
fields = [Name(last='Frankenstein'), Email(address='victor.frankenstein@example.com')]
request = SearchAPIRequest(person=Person(fields=fields), api_key='YOUR-API-KEY')
response = request.send()

#Example 3: First name only with username
request = SearchAPIRequest(first_name='Patrick', username='patrick@twitter', api_key='YOUR-API-KEY')
response = request.send()

Ruby

require 'pipl'

#Example 1: First name only with phone
person = Pipl::Person.new
person.add_field Pipl::Name.new(first: 'J')
person.add_field Pipl::Phone.new(raw: '+15551234567')
response = Pipl::client.search person: person, api_key: 'YOUR-API-KEY'

#Example 2: Last name only with email
person = Pipl::Person.new
person.add_field Pipl::Name.new(last: 'Frankenstein')
person.add_field Pipl::Email.new(address: 'victor.frankenstein@example.com')
response = Pipl::client.search person: person, api_key: 'YOUR-API-KEY'

#Example 3: First name only with username
response = Pipl::client.search first_name: 'Patrick', username: 'patrick@twitter', api_key: 'YOUR-API-KEY'

Java

import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchAPIResponse;
import com.pipl.api.data.containers.Person;
import com.pipl.api.data.fields.*;
import com.pipl.api.search.SearchConfiguration;
import java.util.ArrayList;
import java.util.List;

SearchConfiguration configuration = new SearchConfiguration();
configuration.setProtocol("https");
configuration.apiKey = "YOUR-API-KEY";

//Example 1: First name only with phone
List<Field> fields = new ArrayList<Field>();
fields.add(new Name.Builder().first("J").build());
fields.add(new Phone.Builder().raw("+15551234567").build());
Person person = new Person(fields);
SearchAPIRequest request = new SearchAPIRequest(person, configuration);
SearchAPIResponse response = request.send();

//Example 2: Last name only with email
fields = new ArrayList<Field>();
fields.add(new Name.Builder().last("Frankenstein").build());
fields.add(new Email.Builder().address("victor.frankenstein@example.com").build());
person = new Person(fields);
request = new SearchAPIRequest(person, configuration);
response = request.send();

//Example 3: First name only with username
request = new SearchAPIRequest.Builder()
    .firstName("Patrick")
    .username("patrick@twitter")
    .configuration(configuration)
    .build();
response = request.send();

PHP

<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->use_https = true;
$configuration->api_key = 'YOUR-API-KEY';

//Example 1: First name only with phone
$fields = array(
    new PiplApi_Name(array("first" => "J")),
    new PiplApi_Phone(array("raw" => "+15551234567"))
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), $configuration);
$response = $request->send();

//Example 2: Last name only with email
$fields = array(
    new PiplApi_Name(array("last" => "Frankenstein")),
    new PiplApi_Email(array("address" => "victor.frankenstein@example.com"))
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), $configuration);
$response = $request->send();

//Example 3: First name only with username
$request = new PiplApi_SearchAPIRequest(
    array('first_name' => 'Patrick', 'username' => 'patrick@twitter'),
    $configuration
);
$response = $request->send();

?>

C#

using Pipl.APIs.Search;
using System.Collections.Generic;

SearchConfiguration searchConfiguration = new SearchConfiguration(
    apiKey: "YOUR-API-KEY",
    url: "api.pipl.com/search/",
    useHttps: true
);

//Example 1: First name only with phone
List<Field> fields = new List<Field>()
{
    new Name(first: "J"),
    new Phone(raw: "+15551234567")
};
var person = new Person(fields);
SearchAPIRequest request = new SearchAPIRequest(
    person: person,
    requestConfiguration: searchConfiguration
);
var response = await request.SendAsync();

//Example 2: Last name only with email
fields = new List<Field>()
{
    new Name(last: "Frankenstein"),
    new Email(address: "victor.frankenstein@example.com")
};
person = new Person(fields);
request = new SearchAPIRequest(
    person: person,
    requestConfiguration: searchConfiguration
);
response = await request.SendAsync();

//Example 3: First name only with username
request = new SearchAPIRequest(
    firstName: "Patrick",
    username: "patrick@twitter",
    requestConfiguration: searchConfiguration
);
response = await request.SendAsync();