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 protected]&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.
API response to top_match=true search configuration setting.
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://api.pipl.com/search/[email protected]&key=YOURKEY&top_match=true
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'[email protected]',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.
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";
//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";
/*
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&';
For **Ruby** examples, please contact your Customer Success expert.
curl https://api.pipl.com/search/\[email protected]\&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.