API Reference
HomeMy Account

Match Criteria Parameters

Defining a Match for Your API Integration

If you only want specific data, you should only pay for that specific data, which is why the Search API is priced per match. By specifying match criteria, you can define what you consider to be a match. You can specify 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 three configuration parameters used to define match criteria:

  • match_requirements
  • minimum_match
  • source_category_requirements

Match Requirements

When you want to specify the exact field or fields you need to be returned in the response, you should use the match_requirements configuration parameter. This parameter ensures that the response includes the ‘must have’ data field(s) you specified in the match_requirements parameter. If the response does not contain the data field(s) you specified in the match_requirements parameter, you’ll get a ‘non-matching response’ and you will not be billed for the request.

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, vehicle or social_profile (any url, userID or username from a social media platform).

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.

🚧

You can only use match requirements on fields that are available in the key you are using. For example, if you are using the contact key which does not contain social media data, you will not be able to use "social_profiles" as a match requirement.

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_phone
  • email.personal
  • email.work
  • address.work

In addition to filtering by @type value, there are also a few subfields that can be used as match requirements which are name.first and name.last to require the presence of a first or last name respectively.

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

https://api.pipl.com/search/[email protected]
&match_requirements=new_email
&key=YOURKEY

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

https://api.pipl.com/search/?search_pointer=21a9b8d62049696a7626ac6ff63f3fcde3eb80efe8c1390f867a0de612c66c32d8d84837e3b310dcca29a66233cd4a9195521a0f0b3885395277529e22a2158643a0a9459dc163ad4b7614f453f46428905df6e738ad2c0eeae6e44acfbef89d8e7d5a098baec5fef3bdc6e923cd814d5dbae378de236311c5b09cbe8e6b1d368050aa00033fac8b9f0d2abe822e4d4849e216c86169e03612a6f6a4a3d99a7cb0b9700d01b6b88ca1ba618bd2f817d925a257a254a41a4bbdf301f57b8c7ce0bf48f87a37d9a48f7bf3063f5a6c643b3d4557dc31dc1366cc4961cb360b4ea966528230e5098b1067fafc3c0c6adb03f45483dbcc182330f460bec5a7f2c0360c3eb5f850e22517b409b824a30424b80ea352ced1164da0061b10573d0c43a87ec40d79923970c272a8003323c9fb772e85a38e8aa372080f87502b9d8aa53c457a753eed7642a0e3dbdcfede5451514ec3ee2aca62b8fd91f811f6d4f1fc27c3fae2071bffbad67fa5f4fe39cfc9a8580d7af7e7475503942d0212ad7ff13a6edbaccb8fd77bc48bf1cbd8fe05d1a45914209eeaa49cedefcac4e939dcb0c286a4c33ee3a091c05d8e7be3cadd10df0140450e51397b118889b712dd4c64bcd69c4207e37197812e3cba68cec61bfae135599b1b7539d61823561f2fbfde82cc11543d3db36a8170cde40ecd54285c945b4f3813229fdc817db1f6278be4d902f1d24b6830c96c19237b92189c87143b70aa7d416ce82a4fcaaa1467ddb977198c6358d1e268ff7104528f2078b93a0d4cc2cda8ce84eff12afd312a0fa9b7d3d12e00f3a7c45a28f618935949a1dccd8cdf7c265d34568a7d1ddd2cd7db81544013195d6261f5f5c3243b4cd7bc8667aa74df8c6a59bcd0dc3c62fdf2c3fe1eedb5976b46869e87efa5766e787d8d12142dbb7c3fa329f4b5ed73d249e6d45017bb25d589f01676580471c3c818a0190c0bc6baedd99b8ea32379821fdba1c09f8f1235f58393cc1395e7d48c7820a67b9e09063af4840f87335a30142e2b31051005ab3e42fb3a4c49f5aab084e03cac8e5e15305ee0c1674b25b3bc711770208c9089511e8da1008f72de1b0a7ee26c887a6e860c7638d081a40cc4e517d58b12601c3e9158d39336a706d9fd19c0269428c2da138f607a2cafdcb05577500a6a41fe1d81566932257c48454c6f05e8f4caa627ffcb1b2713989fd606d8f2897e5851003ea860e923871b0fa82c28d39be5adebaf4175bab071be15c64aa9766171982b61e2765a93e8c5fab8262c255e5bd3590e7b0e4f5758039514ab62495c0b44be12b7d618acdccc0808d132cdcbe84a4fac5a05d5d857c79f6d7e1906d4c5e3b0de1135f64f6068b34875b50662f0da643b22b77accf97987047a071647dc084b3061756af331f82b93cf84ec11ba75e9787a88f073c6e60712a53f252548861cc62c1e980b24da25b4c3adec0249a346c2f5a3d8508025fdd611fa001c7b415f812e0e3ec7ee7bcc3ace471dcd1c698b7ae49e016d7366ea03bbc983866a2527da128982393d7641674361c9bd8ac13dc47a894a715eaced6ef612057f2e7bedd8f5f417dbb18d8024cac378b27e14c4ee922bb04b6210f3f89aeb28d7ab46140c5158b5482f2afc7874ee227993c9b4bd21f4b88a7c6b85d8b782ebf8d3f75cc78d8c84d92162ce7764
&match_requirements=new_email
&key=YOURKEY

Minimum Match

The minimum_match parameter can be used to set a minimum match score required to return a match.

What is a Match Score?

Pipl's identity resolution engine allocates a confidence match score between 0 and 1 for each person returned in a response. This match score (shown in the JSON response with the metadata indicator “@match”) indicates the confidence rating that the search engine found the person you’re looking for. Using data science, statistics, and probability, a match score is determined based on the query data entered and data returned from the available sources, a match of 1 is equivalent to 100% likelihood of that person being the one you’re searching for while 0.5 means 50% - for example, if there are 2 possible persons that matched your query. Please take into account that there is always room for minor error since we’re dealing with statistical models.

In the case that the Pipl identity resolution engine is confident that it found the person you’re looking for, it will return just one person with a match score of 1. This is referred to as a “[person response or a “perfect match profile”](ref: response-types#person-perfect-match)”.

When the Pipl identity resolution engine is not fully confident that it found the person you’re looking for, based on the search inputs you have supplied and the data found, it will return a response with a list of up to 50 possible-persons, one of which may be the person you are looking for. The possible-persons array is ordered in descending order of match score where the person with the highest match score is at the top of the list.

📘

The match score (@match) is a very long decimal number but in the API response, this is rounded off to 2 digits after the decimal point. So even though persons in a possible_person response might appear to have the same match score, e.g 0.25, their actual match score could actually be different. Similarly a match score of 0.0 indicates a decimal number less than 0.05.

Setting a Minimum Match

The minimum_match query parameter can be set at a decimal value between 0 and 1. When set, only person profiles with a match score above or equal to the minimum_match setting specified will be returned in a response.

When leaving the minimum match at the default setting of 0, there is no filtering on the match score, and all types of responses will be returned. For example, if you set the minimum_match to 0.5, only persons in the response that have a match score equal or higher than 0.5 will be returned. This means you will receive one of the following:

  1. a person response
  2. a possible_persons response with each person having a match score equal or above 0.5
  3. a non-matching response.

By setting the minimum_match to 1, you are telling the API to return only person responses (i.e. single matching profiles). This means you will never receive a possible_persons response and will only receive either

  1. a person response
  2. a non-matching response.

Also note that the top match feature is an alternative way to process possible person responses which will also eliminate possible person responses.

👍

Finding the right minimum match level

If you are not sure what the right minimum_match is for you, first decide if you want to see possible person responses or not. If you only want to work with person responses, set the minimum_match to 1 or consider using the top match feature. If you are deciding on a minimum match between 0 and 1, start with any figure and slowly change it as you go. Lower it if you feel you might be missing data or raise it if you are getting too many irrelevant profiles.

See How to Handle Possible Person Responses for more details and options for handling possible person responses.

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)
&minimum_match=0.5
&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 minimum_match=0.5
    -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