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) or top_match=true when including demographic info
  • match_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](ref: Job) below. 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=true
  • match_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)

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 below

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=0
  • show_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=0
  • show_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.

Searching by Specific Query Parameters

Multiple Phones, emails or Addresses

Using multiple instances of a particular data field in a search query requires using a full person search

https://api.pipl.com/search/?key=YOUR_KEY&show_sources=matching&person={ "names": [ { "first": "Clark", "last": "Kent" } ], "addresses": [ { "city": "Chicago", "state": "IL", "country": "US" }, { "city": "Wichita", "state": "KS", "country": "US" } ], "emails": [ { "address": "[email protected]" }, { "address": "[email protected]" } ], "phones": [ { "raw": "+1(312) 684-5000" }, { "raw": "(312) 352-9327" } ] }
person=
{
  "names": [
    {
      "first": "Clark",
      "last": "Kent"
    }
  ],
  "addresses": [
    {
      "city": "Metropolis",
      "state": "IL",
      "country": "US"
    },
    {
      "city": "Wichita",
      "state": "KS",
      "country": "US"
    }
  ],
  "emails": [
    {
      "address": "[email protected]"
    },
    {
      "address": "[email protected]"
    }
  ],
  "phones": [
    {
      "raw": "+1(312) 684-5000"
    },
    {
      "raw": "(312) 352-9327"
    }
  ]
 }

Social Profiles (Facebook, LinkedIn and others)

You can search Pipl by social services by the username, userID or even a profile URL. For the complete list of supported services, such as GitHub, Tiktok and others, please see the list of supported services .

[email protected]

OR

[email protected]

OR

url = https://linkedIn.com/in/ClarkKent
https://api.pipl.com/search/?key=YOUR_KEY&show_sources=matching&[email protected]

US VIN (Vehicle Identification Number)

The username parameter is used to search by a vehicle VIN using the format ########@vin

[email protected]
https://api.pipl.com/search/?key=YOUR_KEY&show_sources=matching&[email protected]

CPF (Brazilian Identification number)

The username parameter is used to search by a CPF using the following format "###########@cpf"

[email protected]
https://api.pipl.com/search/?key=YOUR_KEY&show_sources=matching&[email protected]

NPI (US National Provider identifier - medical professionals)

The username parameter is used to search by an NPI using the following format "##########@npi"

[email protected]
https://api.pipl.com/search/?key=YOUR_KEY&show_sources=matching&[email protected]

Job/Education

Searching by job or education in a search query requires using a full person search

https://api.pipl.com/search/?key=YOUR_KEY&show_sources=matching&person={ "names": [{ "raw": "Clark Kent"   }], "educations": [ {"school": "University of Chicago"} ], "jobs": [{"organization": "The Wallstreet Journal"}, {"title": "Field Reporter"}] }
person=
{
        "names": [{
                        "raw": "Clark Kent"   }],
        "educations": [ {"school": "Metropolis University"} ],
        "jobs": [{"organization": "The Daily Planet"},
                 {"title": "Field Reporter"}]
}

Relationship

You can search for a person that has a connection to another. Note that in the relationship object only the name part will be used in the search.

https://api.pipl.com/search/?key=YOUR_KEY&show_sources=matching&person= { "names": [ { "first": "Clark", "last": "Kent" } ], "relationships": [ { "names": [ { "first": "Sam", "last": "Smith" } ] } ] }
person=
{
  "names": [
    {
      "first": "Clark",
      "last": "Kent"
    }
  ],
  "relationships": [
    {
      "names": [
        {
          "first": "Lois",
          "last": "Lane"
        }
      ]
    }
  ]
}

Email in MD5 format

You can search for an MD5 as follows. Please be sure to normalize your email address following the MD5 Calculation guidelines before applying the MD5 hash.

https://api.pipl.com/search/?key=YOUR_KEY&show_sources=matching&person= { "emails": [ { "address_md5": "b095275aa233df8e857dbca662512ca4" } ] }
person=
{
  "emails": [
    {
    "address_md5": "b095275aa233df8e857dbca662512ca4"
    }
  ]
}

Did this page help you?