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