Best Practices By Use Case
Pipl Search applies to a variety of use cases. Each use case has unique objectives and requirements, as well as preferred ways of working with the Pipl Search API. This article provides recommendations based on successful approaches for key use cases. This provides a starting point for integration and optimization efforts; adapt it based on your specific goals and requirements.
Contact Enrichment
The contact enrichment use case is using the Pipl Search API to add new data points to an existing profile or contact. New data might include contact information such as phone numbers, email addresses or social media profiles.
To return the most relevant results for each contact, limit queries to only those that have the information you need. To do this, set your match requirements appropriately. For example if you are enriching contacts with social media profiles, you can limit the query to only return matches for people that have a social media profile:
match_requirements=social_profiles
Use boolean operators (OR and AND) to further refine the match requirements.
Recruiting
LinkedIn to Contact Information
LinkedIn URLs, usernames or UserIDs are often sufficient, on their own, to match to a profile and find contact information. You can also try adding supplementary demographic information such as a name and location (even just a country or country + state). The sources layer includes tags for professional skills and courses that may be relevant to your application.
Recommended Parameters:
minimum match=1.0(for LinkedIn alone) ortop_match=truewhen including demographic infomatch_requirements= 'phone OR email'live_feeds=false(except for low volume/throughput)show_sources=matching
SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', minimum_match=1.0,
match_requirements='phone OR email', live_feeds=False, show_sources='matching')
request= SearchAPIRequest(url='https://www.linkedin.com/in/clarkkent')
response=request.send()
contact_phone_1=response.person.phones[0].number
contact_email_1=response.person.emails[0].address
Name and Job to Contact Info
Searching by job requires using a full person search; See Searching by job. If you have job history, consider adding multiple jobs to increase the probability that Pipl Search finds the individual. Adding a LinkedIn profile, if you have it, may increase your match rate (see the Linkedin to Contact Information section above). When searching for work email addresses, you can get a greater fill of inferred work emails by reducing the threshold needed for an inferred email to be included in a response (with parameter minimum_probability).
Recommended Parameters:
top_match=truematch_requirements='phone OR email'live_feeds=false(except for low volume/throughput)minimum_probability=0.6
SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', top_match=True,
match_requirements='phone OR email', live_feeds=False, minimum_probability=0.6)
Real Estate
A common use-case for the Search API in real estate is to find contact or social media information for the owner or resident of an address. To do this, use the address and any other information you have on the person as the query input. While a US Address alone meets the minimum requirements for a query, this type of search will usually return a possible person response, since there are almost always multiple people connected to a single address (multiple residents, previous residents, owner and renter). Include a name and/or other information to help the API determine which of those connected people is the individual you are searching for.
To ensure the API reads the address correctly, we recommend splitting it into individual components (country, state, city, zip, street & house) to send to the API. The API can also take an address in raw form (the full address in a single input parameter), but you will need to verify that our API is parsing correctly for your address format.
For US addresses, the source layer includes tags for home ownership (apn), most recent sale, and home type. This information can be used to verify current home ownership. Search for tags with the classifications 'apn', 'last_sale_date' and 'type'. See popular tag classifications for more details.
Recommended Parameters:
top_match=truematch_requirements= 'phone OR email OR social_profiles'show_sources=alllive_feeds=true(depends on expected volume/throughput)
SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', top_match=True,
match_requirements='phone OR email OR social_profiles', show_sources='all',live_feeds=True)
Investigation and Background Checks
Routine background checks, criminal and OSint investigations use Pipl Search to uncover as much useful information as possible on an applicant or person of interest.
While you can run a search with just a single piece of information (see minimum search requirements ), including as much information as possible in your query will generally connect to more records and return more data in your response. The sources layer can provide additional data and context to your person of interest.
Recommended Parameters:
show_sources=all
*live_feeds=true(up to 10 QPS)
SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', show_sources='all', live_feeds=True)
Reverse relationship searches
Use reverse relationship searches to discover more about a person you find in the relationship section of a Pipl Search result. Say you are searching for Alex Jensen and you see in your API response that he has a family relationship with Brian Jensen and you want to find out more about him. To do this, swap the name element with the relationship element from the API response, in this case name is "Brian Jensen" and the relationship to "Alex Jensen".
See how to perform a search using the relationship parameter
Identity Verification (IDV) and Fraud
The Search API can be used in fraud and Identity verification in order to verify the identity of an individual, to validate whether specific data points connect to them, and to build a full picture of the identity behind a piece of data. In addition, the data from Pipl search can be used in decisioning engines or machine learning models to calculate fraud risk scores.
It is especially important in these use cases to make sure that all query parameters provided to the API are known to be accurate and connected to the person you are searching for. Leave out any data points that are not certain to be connected to a person.
Pipl Trust
Pipl Trust is a separate Pipl product that helps identify and score trust for a data point or action based on the connectivity of the data, the profile connected to the data, and other trust signals.
For more information about using Pipl Search as part of a machine learning model see Using-Pipl-Search-in-Machine-Learning-and-Data-Driven-Decisioning
Data Point Validation
One common use of the Pipl Search API in the identity verification and fraud space is to validate whether certain data points connect to an individual. For example if you have a user account and the phone number changes, you want to validate if that new phone number is connected to the account owner. When doing this, separate your data into two categories: 1. Known data with a confirmed link to the individual and 2. Data to be verified. Only send the known data in the search query, then in the response, check for the data you are trying to confirm.
Pipl Search does not have 100% fill of all data points, so not finding the data point in the response is not definitive proof that it is not connected to the individual.
Expect lower latency responses for searches by just a phone or email address.
It may be helpful to see the source layer to check what source was used to validate the data point.
Recommended Parameters:
live_feeds=false(except for low volume/throughput)minimum_probability=0show_sources=all
SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', show_sources='all', live_feeds=False, minimum_probability=0)
Identity Discovery and Scoring
Another identity verification use case is to try to build a profile for the identity behind a data point and, in some cases, provide a score for that identity.
You may want to access the source layer to be able to include tag data such as vehicle and home ownership and professional credentials in your analysis.
Recommended Parameters:
live_feeds=false(except for low volume/throughput)minimum_probability=0show_sources=all
SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', show_sources='all', live_feeds=False, minimum_probability=0)
PiplTrust is a separate Pipl product that helps identify and score the trustworthiness of a data point or action based on connections between elements, associated profiles, and other signals.
General Recommendations
Performance Optimization
Depending on the metrics that are most important to your application, there are different configuration strategies you can use. Often optimizing for one metric comes with trade-offs in another metric, so be sure to balance your approach according to your priorities.
Optimizing for Match and Fill Rates
In general, the more data you provide in search query parameters, the better the match and fill rate will be on a search response. Try adding more information about the person to the query. For example, if you’ve searched by email address alone, try adding the name and location to the query. Adding even just a country or a country + state to a search query can significantly increase the match and fill rate.
When searching for individuals in the US, turning on live feeds can also slightly increase your match and fill rates. Live feeds are data partners outside of Pipl's infrastructure that can provide additional data (approximately 2-3% more) specifically within the USA. Please note that this will come with the downside of increased latency and decreased throughput.
Optimizing Query Speed
The most important factor to increase speed is to turn off live feeds. This will both decrease latency and increase your throughput rate limit You can do this by setting the parameter 'live_feeds' to 'false'. Please note that turning off live feeds will lead to a slight reduction in data match and fill rates (see Optimizing for Match and Fill Rates section above)
If low latency is your top priority, there are a few single-parameter queries that will run faster than multi-parameter queries. These include phone-only, email-only and address-only queries. Keep in mind that these single parameter queries come with significant trade-offs in terms of match and fill rate, so be sure that the benefit in latency is worth the cost of data fill.
Updated 5 months ago