HomeMy Account

Match Criteria Parameters

Defining a Match for Your API Integration

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 as atomic expressions in your match requirements condition:

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

🚧

Possible person responses do not contain email addresses or social urls. Therefore, using match requirements of email or url will result in no possible person responses being returned. When using these match criteria, consider using the top_match parameter to include the email and social urls of the top possible person in a full person response.

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

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. Using this prefix is effective when you have a piece of data (e.g. an email) but want other data of the same field type (e.g. additional emails other than the one you have).

📘

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]

The ‘new_’ prefix can also be used in combination with a search pointer search to check for any data updates after an interval of time (not more frequently than every 3 months).

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. Setting the source category in the request is useful if you are only interested in a very specific piece of data that is related to one of the categories. Please note that in order to see the sources, you will need to set the show_sources parameter.

Match Criteria Structure

A match requirement or source category requirement may be either one atomic expression or two or more atomic expressions combined using the following operators and parentheses.

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

Please note the following about using match criteria:

  • Parentheses allow creating more complex rules. Whatever is inside a parenthesis will be evaluated to a truth value before the outer condition
  • The source category requirements and match requirements are evaluated separately
  • Incorrect structuring of match criteria will result in a error response(HTTP code 400)

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