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

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.

404404

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