Using Match Criteria

Normally you would pay for each API request that resulted in a match, whether a match is a perfect match or a list of possible persons.

You can exercise control over your bill by specifying a minimum criteria that a person must meet in order to be returned. If the criteria isn’t met, you will receive an empty response and won’t be charged.

There are two configuration parameters used to define match criteria:

  • match_requirements, and
  • source_category_requirements

Match Requirements

You can use one or more of these field names in your condition as the most atomic expression:

  • name
  • address
  • phone
  • email
  • job
  • education
  • image
  • username
  • user_id
  • dob
  • url
  • gender
  • language
  • origin_country
  • social_profile

The criteria will be met if the response contains the requested field.

Match Only on New Data

You can prefix any field name with “new_,” in which case the criteria will only be met if the response includes data of that type that was not included in the original query.

🚧

For example, if your query is [email protected] and you ask for new_emails, you will only get a response if it contains emails other than [email protected]

Match by More Granular Data Types

You can append “.TYPENAME” to any field name, where TYPENAME is any recognized @type value of the data field. See the Data Field pages to see the available @types that can be used for each data field. Some frequently used types include:

  • phone.mobile
  • phone.work
  • email.personal
  • address.work

Source Category Requirements

You can also use any of the source categories as the atomic expression. The criteria will be met if the response contains at least one person (perfectly matching or a possible person) that includes a source of the requested category. For example, setting source_category_requirements='personal_profiles' would only return a match if the response contained data from a personal social media profile. Please note that in order to see the sources, you will need to set the show_sources parameter.

Parsing

When we receive a match requirement criteria, we parse it based on the following rules:

  • An expression is either one atomic expression (field name or source category) or a combination of many using the following operators.
  • Parentheses allow creating more complex rules. Whatever is inside a parenthesis will be evaluated to a truth value before the outer condition.

Operators

  • " AND " : Both the preceding and the following expressions must be met.
  • "|" or " OR ": Either the preceding or the following expression must be met.

Structuring Rules

An expression may be either one atomic expression or two or more atomic expressions combined using operators and parentheses.

Example

https://api.pipl.com/search/[email protected]
&match_requirements=(phone.mobile|email.personal)
&source_category_requirements=personal_profiles
&key=YOURKEY
curl https://api.pipl.com/search/ \
    -d [email protected]
    -d match_requirements=(emails.personal or phones.mobile)
    -d key=YOURKEY

curl https://api.pipl.com/search/ \
    -d [email protected]
    -d match_requirements=(emails and jobs)
    -d source_category_requirements=professional_and_business
    -d key=YOURKEY