Top Match

Search Configuration Parameter "top_match=true" returns the best high-ranking match to your search. The API will return either a Person (when a high-scoring profile is found) or a No Match (when no high-score profile is found). It never returns a Possible Persons response.

Basics

https://api.pipl.com/search/?email=clark.kent@example.com&key=YOURKEY&top_match=true

**Default Value: top_match=false; For more detailed syntax, click here.
Related Topics: Minimum Match, Person Objects & Possible Person, API Response

Effects to API Response

When using the top_match=true, the Pipl API will return either a Person response or No Match response; it will never return a Possible Persons array.

To see differences based on scenario, see table below.

top_match=false (default)	Versus	top_match=true
When...	→	This will happen...
When response returns a single individual (a Person response).		API still returns a fully enriched Person response (unchanged).
When response returns Possible Persons and the first person has a high-probability match.	→	The API (after making a second iteration behind the scenes) will return that first profile as a fully enriched Person response.
When response returns Possible Persons but the first person might not have a high-probability match score.	→	The API returns an empty or No Match response.

Syntax & Using Code Libraries

If you're using one of Pipl's API code libraries, you can easily enable the top_match feature within your queries. Simply add &top_match=true to your API queries with the Pipl API to activate this feature.

HTTPS

https://api.pipl.com/search/?email=clark.kent@example.com&key=YOURKEY&top_match=true

Python

SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', use_https=True, top_match=True)
request = SearchAPIRequest(person=Person(fields=fields)) 

#or more simply:
request = SearchAPIRequest(email=u'clark.kent@example.com',api_key=u'YOURKEY',top_match=True)

#You can also modify the base URL.
SearchAPIRequest.BASE_URL = u'https://api.pipl.com/search/?top_match=true' 
request = SearchAPIRequest(person=Person(fields=fields), api_key=YOURKEY) 

#Requires Pipl API Python Code Library version 5.2.0 or higher.

C#

using System;
using Pipl.APIs.Search;
using Pipl.APIs.Data.Containers;
using Pipl.APIs.Data.Fields;

SearchConfiguration defaultConfiguration = SearchAPIRequest.DefaultConfiguration;
defaultConfiguration.UseHttps = true;
defaultConfiguration.ApiKey = "YOURKEY";
defaultConfiguration.MatchRequirements = "address";
/* Use the Url parameter to manually set HTTPS and top_match in target. */
defaultConfiguration.Url = "https://api.pipl.com/search/?top_match=true";

Java

//Update the default configuration on init, which will be used.
//Use the extraParams variable of the defaultConfiguration. See example below: 

SearchConfiguration defaultConfiguration = SearchAPIRequest.getDefaultConfiguration();
defaultConfiguration.extraParams = "&top_match=True";

PHP

/*
Once you instantiate a PiplApi_SearchAPIRequest object, you will need to change the base_url from:
*/

public static $base_url = 'api.pipl.com/search/?';  
/* to the following to execute a request */
$base_url = 'api.pipl.com/search/?top_match=true&';

Ruby

For **Ruby** examples, please contact your Customer Success expert.

cURL

curl https://api.pipl.com/search/\?email=clark.kent@example.com\&key=YOURKEY\&top_match=true

When To Use top_match Parameter

Consider using the top_match parameter if it meets your use case and requirements for acceptable identity resolution.

• “I only want Person responses” —Your application logic or use case might only work with Person responses, so you want to remove the chance of Possible Person responses.
• “I don’t want to send two queries” —Most users use a 2-tier search approach. If they get a Possible Persons response, first they choose the best person from the list of Possible Persons, with code or in manual review. Next, they call the API a second time with the search pointer to get the best possible Person response. By using the top_match parameter, you need only call the API once and can bypass the middle step.

Final Notes

The top_match setting is not beneficial for every use case. However, when properly used, top_match can provide a simpler integration and eliminate the need for two successive API calls.