An HTTP status of 200 indicates that the Pipl Search API received and processed the query without errors. See Errors page for information on unsuccessful calls. There are three types of responses that can be returned as HTTP status 200

Person (Perfect Match)

A Person response is indicated when the @persons_count is equal to 1 and the JSON response has a “person” object in it. This means that the API used the information in the query and was able to resolve on a single profile that matches the query with high confidence.

Please note:

  • On a pay-per-match model, this response is charged as a match.
  • The @match score for the Person will be 1, indicating high confidence that the profile is connected to the individual
  • The available_data section provides a count for the number data types that Pipl knows about the person

Example:

{
    "@http_status_code": 200,
    "@visible_sources": 181,
    "@available_sources": 182,
    "@persons_count": 1,
    "@search_id": "2205052029521219486728632842045149061",
    "query": {
        "emails": [
            {
                "@type": "personal",
                "address": "[email protected]",
                "address_md5": "a294a3214cebe4923c075bc531765274"
            }
        ]
    },
    "available_data": {
        "premium": {
            "relationships": 22,
            "usernames": 4,
            "jobs": 17,
            "addresses": 16,
            "phones": 10,
            "mobile_phones": 1,
            "landline_phones": 9,
            "educations": 2,
            "vehicles": 1,    //coming soon!
            "languages": 1,
            "user_ids": 8,
            "social_profiles": 9,
            "names": 1,
            "dobs": 1,
            "images": 4,
            "genders": 1,
            "emails": 6
        }
    },
    "person": {
        "@id": "a587e4f7-0ad8-4880-9686-72bfd543e297",
        "@match": 1.0,
…

Possible Person

A Possible Person response is indicated when the @persons_count is between 1 and 50 and the JSON response has a “possible_persons” array in it. This means that the API was able to find data connected to your query parameters, but did not have enough information to cluster these into a single matching profile. A Possible Person response is more likely when sending a single data point like an address or phone number that can be connected to multiple people. A Possible Person response can return up to 50 Possible Persons and each Possible Person will contain an @match score that indicates the probability that the profile is connected to the query information. On the pay-per-match model, this type of response is charged as a single match (not for each possible person in the response)

Each Possible Person has been clustered by the API into a profile, and the API returns a list of people, ordered by most likely to least likely individual, in a high level summary with just enough information to distinguish each individual. In some cases, the person you are searching for is found in more than one of these possible person profiles.

Please note:

  • Certain fields such as emails and social media urls are always excluded from a Possible Person response. Expand a Possible Person using the search pointer to check for these fields see How to work with Possible Person responses below.
  • The available_data summary is the count of the sum of all data fields for all people found in the Possible Person response
  • Possible Persons with a very low match score such as 0.0, are related search results. The actual match score is less than 0.05. These will be included in a Possible Person response by default, but can be excluded by raising the minimum_match parameter.
  • If you would like to see which sources were used to build each of the possible person profiles, you can use the show_sources and show_sourceids parameters together. Read more details here.

Example:

{
    "@http_status_code": 200,
    "@visible_sources": 161,
    "@available_sources": 161,
    "@persons_count": 16,
    "@search_id": "2205052032051932765166845180551538640",
    "query": {
        "names": [
            {
                "first": "Garth",
                "last": "Moulton",
                "display": "Garth Moulton"
            }
        ],
        "addresses": [
            {
                "country": "US",
                "state": "NC",
                "display": "North Carolina, United States"
            }
        ]
    },
    "available_data": {
        "premium": {
            "relationships": 36,
            "usernames": 12,
            "jobs": 31,
            "addresses": 40,
            "phones": 18,
            "mobile_phones": 3,
            "landline_phones": 15,
            "educations": 2,
            "vehicles": 4,    //coming soon!
            "languages": 9,
            "user_ids": 27,
            "social_profiles": 28,
            "names": 16,
            "dobs": 7,
            "images": 13,
            "genders": 16
        }
    },
    "possible_persons": [
        {
            "@match": 0.73,
            "@search_pointer": "87827c7da793b5ec8edb2b64fc738b0…

How to Handle Possible Person responses

You have several different options for handling Possible Person responses. The API has a few built-in configuration parameters to help configure the API based on your desired option.

Option 1 - Return all Possible Persons (default)

Leaving the configuration parameters at their default settings of top_match=false and minimum_match=0, will return all Possible Persons in the response.

Option 2 - Return most likely possible person only

Set the configuration parameter top_match=true to only see a possible person with the highest @match score. This configuration will automatically run the top possible person through a subsequent free-of-charge search to return a Person response. Using top_match can increase your latency as there can be as much as two calls to the API for Possible Person responses. Using this method, you won’t need to work with the “possible_persons” array in your code.

Option 3 - Don’t return Possible Person responses

Set the configuration parameter minimum_match=1 to filter out Possible Person responses entirely. As with option #1, you will not need to work with Possible Person array in your code, but it will return a lower match rate compared to option #1.

Option 4 - Return Possible Persons above a threshold

Set the configuration parameter minimum_match between 0 and 1 to set the minimum @match score for a possible person to be included in a response. For example, Set minimum_match=0.25 to return all Possible Persons with a @match score of 0.25 and above (corresponds to a greater than 25% probability of being connected to your query parameters). Note that when using this with the show_sources parameter, sources will also be filtered by this @match score.

Option 5 - Expand Possible Person

Each possible person returns with a search pointer that will allow you to do a more expanded search on the Possible Person. This expanded search will almost always return a Person object and can return more information than the original possible person including emails and social media urls should these be available for the person. To do this, pick the possible persons that you want to look at more closely, and run a secondary search using search_pointer of those Possible Persons and the search pointer query parameter. Note that the secondary search will be charged on a pay-per-match model.

No Match

A No match is indicated by a @persons_count of zero and the absence of a “person” object or “possible_persons” array in the JSON response. This means that the either API was not able to find any information connected to the query parameters you sent us (@persons_count = 0), or you used the match criteria parameters (@persons_count>0, but no “person” or “possible_persons” in the response, read more here ).

On a pay-per-match model, this response is not charged.

If you get a no match, you may want to try adding additional query parameters to increase the probability that the API is able to find a match. Certain configuration parameters such as match_requirements , minimum_match, top_match, live_feeds and source_category_requirements also can affect your match rate. Note that when you use the match criteria parameters, the @persons_count and available_data will indicate that Pipl does have data for your search, and provides you an opportunity to see what data was available should you relax your criteria.

Example:

{
    "@http_status_code": 200,
    "@visible_sources": 0,
    "@available_sources": 0,
    "@persons_count": 0,
    "@search_id": "2205052033282219693884262552851980308",
    "query": {
        "emails": [
            {
                "@type": "personal",
                "address": "[email protected]",
                "address_md5": "de28975047b32ed71140a6359deb7fee"
            }
        ]
    }
}

Response types by search input types

The type of query input used may influence the type of response, based on the query information you provided, but also regarding the public data records available. Remember that Pipl’s technology operates like a search engine in that we will try to find the person(s) you are looking for. Here are some reasons why your search returned one of the three response types, and which one will typically be returned.

Search query inputPersonPossible PersonsNo Match
Single email addressThe person behind the email address was found

Common
The email points to multiple individuals. When Pipl doesn’t have the email in our records we will break this down by prefix and suffix. From the prefix a username or name may be obtained, and from the suffix a may be obtained.

Common
Pipl doesn’t know about this email address, or match criteria was used

Uncommon
Single phone numberThe person behind the phone number was found

Common
The phone number points to multiple individuals. This phone number could have been recycled, or an office phone number

Common
Pipl doesn’t know about this phone number, or match criteria was used

Uncommon
Name aloneThe person has a very unique name

Rare
Pipl has a global index of data, so searching for a name alone is not recommended, as people share names in the world.

Very Common
Rare
Name + Address: Country, State, City + ZipIt’s recommended to use topmatch=true to get more Person responses

_Common
People share names, and if Pipl does not have the address for the individual, then individuals with similar names will be returned

Common
Uncommon
Social URLA social URL is a strong indicator of identity, and there is typically only one person with one social profile per network in the world

Very Common
It is rare that such responses will return, because a social URL is such a unique identifier

Rare
Pipl doesn’t know about this social profile, or match criteria was used

Uncommon
UsernameIf a very unique username, a Person response will be returned

Very Common
Different people can use the same username across social networks

Uncommon
Pipl doesn’t know about this username, or match criteria was used

Uncommon
UserID@serviceA UserID is a strong indicator of identity, and there is typically only one person with one social profile per network in the world

Very Common
It is rare that such responses will return, because a UserID is such a unique identifier

Rare
Pipl doesn’t know about this userID, or match criteria was used

Uncommon
Name(s), Phone(s), Address(es), Email(s) + moreThe more information you provide about the identity of the individual, the more likely that Pipl will find the person you are looking for

Common
Not enough info provided or data combines elements of multiple individuals

Common
Uncommon