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.

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:

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:

📘

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.

• 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.

• 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.