Skip to content

Identifying persons

When identifying persons in an onboarding processes, or when using autofill to pre-populating fields in a web form, you will use the Find API.

The Find API accepts a variety of matching parameters, that all will be used to identify the person in your available sources.

Risks of using in public web apps

Integrating the Find API in a publicly available web app can expose personal data, which may violate principles outlined in GDPR (article 5). To reduce risk:

  • Require login (e-ID or password)
  • Use data for backend processing only, without displaying it to the user
  • Mask output (e.g., A** E*****, S******** 17, **121 E*********)

Failing to protect this data may lead to legal and reputational consequences. To learn more on how to protect your data, contact us or your key account manager.

Not all persons are findable

Using the Find API is both less restricted, and more restricted, in its response than the Consumer match API.

For example, you might be able to find persons using only phone numbers, but a person with an active telemarketing restriction will not be returned in the response.

There are more rules applied to this matching context, all of which might differ per market. To learn more contact us or your key account manager.

Basic API call

To find a person, you will need to know in which market the query should be directed to.

Find person request example
curl {API_URL}/markets/{MARKET}/persons/_find \
  -X POST \
  -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "legalId": "191212121212"
  }'

The response will either return 200 OK and return the found person, or 204 No Content with a empty response body if no person was found.

Find person response example
{
  "status": {
    "active": true
  },
  "legalId": {
    "identityNumber": "191212121212"
  },
  "metadata": {
    "updatedTimestamp": "2025-05-12T13:24:11.130620139Z",
    "sources": [
      {
        "updatedTimestamp": "2025-05-12T13:24:11.130620139Z",
        "name": "DUN_BRADSTREET",
        "market": "SE"
      }
    ]
  }
}

Best practices

Provide as much data as you can

The more input we have the more likely we are to identify the person. It's better to send more data, as granular as possible, to guarantee a hit.

Mask data in the backend

If you plan to show masked values in your web application, your backend should already mask the data before returning it to your frontend.

This minimizes risk in case of malicious use of your web application.