Integration Checklist

As you integrate the Pipl Search API, you want to make sure that your integration is robust and optimized. This integration checklist is meant to help guide you through the process and make sure you covered all your bases.

Optimizing Requests:

  • Do you need match criteria? Set correctly to get as much useable data as possible
    • If multiple data fields can be used in a response, use the OR parameter
    • Use @type metadata for more granular filtering, if necessary
  • What query parameters are being sent to Pipl?
    • Generally, more info in the query leads higher match rate and data fill
    • Take a look at some common search queries to get an idea for what you can include in a search query
  • Are you optimizing for speed/throughput or maximum data fill ?
    • Parameter live_feeds=true for 2-3% more data fill, but with increased latency (1 to 2 seconds) and a maximum QPS of 10 (compared to 20 with live_feeds=false)
  • Have you implemented query rate throttling?
  • Are you validating data before sending?
    • Pipl Search uses Google's libphonenumber to validate phone numbers. Raw phone numbers are in international format
    • Validate email format
  • Are you ensuring your queries meet minimum requirements?

Reading a Response:

  • Are you taking advantage of the source layer?
    • Set parameter show_sources=matching
    • Attributes data points in the response to their source
    • Tags in the source layer provide additional data such as professional skills and courses, vehicle info, NPI, home ownership, and death records
  • Are you keeping data in the order that Pipl returned it?
    • The data items in a Search response will be ordered by relevance and recency
  • Are you paying attention to last seen and valid since dates?
  • Are you using the metadata @type(example: phone type= mobile vs work)
  • Can you handle null data fields?
    • If the response doesn’t have a data field, that field key will be removed. For example, if a response has no jobs, there will be no jobs key or field in the response.

Processing and storing a query and response:

  • How do you want to handle possible person responses?
    • Show me the best possible person in the response (parameter top_match=true)
    • Don’t show me possible person responses (parameter minimum_match=1)
    • Only show me possible persons above a certain threshold of match (parameter minimum_match between 0 and 1)
    • Dig deeper into possible person responses (use a two tiered search approach by searching on the search pointer of one or all of the possible persons)
    • Show me all possible persons (make no adjustments to configuration parameters)
  • Are you logging all queries made to the Pipl API?
    • Also log the @search_id for troubleshooting with Pipl
  • Do you have appropriate error handling in your code?
  • Are you logging and reviewing warnings and errors returned by the Pipl Search API?
    • Review warnings in order to optimize searches (address or name was parsed wrong, a field was ignored because it was invalid)


  • Have you tested your search flow using the non-billed example email, [email protected]?
  • Reach out to your customer success team or contact customer support to answer any questions or review your search strategy