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

• a Person response (also known as a perfect match),
• a Possible Person response (also known as a multiple match)
• a No-Match.

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.