The Phone To Name endpoint allows you to retrieve the most plausible name associated with a given phone number from an heterogeneous set of data sources.

Request

Following an example of a Phone To Name

curl --request POST \
     --url https://api.trustfull.com/data/1.0/phone-to-name \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-key: [your_app_key]' \
     --data '
{
     "transaction_id": "your_transaction_id",     
     "phone_number": "1212xxxxxxx"
}'

Here's a detailed explanation of all fields needed for the api call:

Response

All lists in the response are ordered by count, from the most to the least frequent.

Following is an example of the response:

{
  "is_valid_format": true,
  "first_name": "Tony",
  "last_name": "Stark",
  "confidence": "HIGH",
  "has_phone_to_name_match": true,
  "names": [
    {
      "first_name": "Tony",
      "last_name": "Stark",
      "count": 5
    },
    {
      "first_name": "Peter",
      "last_name": "Parker",
      "count": 1
    }
  ],
  "names_cities": [
    {
      "first_name": "Tony",
      "last_name": "Stark",
      "city": "New York",
      "count": 2
    }
  ],
  "cities": [
    {
      "value": "New York",
      "count": 2
    }
  ],
  "names_dobs": [
    {
      "value": "1985-05-15",
      "count": 1
    }
  ],
  "names_with_dobs": [
    {
      "first_name": "Tony",
      "last_name": "Stark",
      "value": "1985-05-15",
      "count": 1
    }
  ],
  "names_addresses": [
    {
      "value": "200 Park Avenue, New York, NY 10166",
      "count": 2
    }
  ],
  "names_with_addresses": [
    {
      "first_name": "Tony",
      "last_name": "Stark",
      "value": "200 Park Avenue, New York, NY 10166",
      "count": 2
    }
  ],
  "country_code": "US"
}

Here's a detailed explanation of all fields returned:

For any non-2xx response, refer to HTTP Status codes.

FAQ

Following are some common questions for this specific API:

📘

Why do I need to pass a transaction_id?

This value is useful to refer to a specific transaction in the system. Using only the phone number can lead to collision in case of duplicated call for the same phone number. Transaction id must be unique across all trustfull api endpoints.

📘

What is the supported phone_number_format?

The phone_number parameter must be submitted in international format, using digits only. This means the number should include the country code directly followed by the national number, without any leading zeros, plus symbols, spaces, or special characters.

📘

What happens if I pass an invalid phone number?

We strongly encourage you to validate the phone number format before making a request, or to use our Phone Validation endpoint. If the phone_number provided has an invalid format, the response still contains every field, but only is_valid_format (false) carries meaningful information—every other field is null. The call is charged at the same rate as a standard API call.

📘

Why do date of birth, address and city each appear twice in the response?

Because we return two different views of the same information. One view is aggregated for the phone number (cities, names_dobs, names_addresses): it lists every value we have seen linked to that number, with how many times we saw it, without attributing it to anyone in particular. The other view is attributed to a specific person (names_cities, names_with_dobs, names_with_addresses): each entry carries a first name and last name alongside the value. Use the attributed fields whenever you need to tie a value to an individual, and the aggregated ones when you just want the overall picture of the number.

Please note the naming: despite the names_ prefix, names_dobs and names_addresses are the aggregated lists, not the attributed ones. The attributed equivalents are names_with_dobs and names_with_addresses. For cities the pair is names_cities (attributed) and cities (aggregated).

📘

Can I pair an address with a city by their position in the list?

No. Each list is sorted independently by how frequently we observed each value, so the first address and the first city are not guaranteed to belong to the same person or the same record. To link an address to a city, match on first_name + last_name across names_with_addresses and names_cities.

📘

When names contains more than one person, should I treat each one as a separate identity?

Treat them as candidates rather than confirmed identities. Multiple entries can mean genuinely different people (a shared or family line, a business number, a previous owner of the number) or simply different spellings of the same person that we could not safely merge. The count field tells you how often each name was observed, and the list is ordered from most to least frequent.

If you need a single answer, use the top-level first_name, last_name and confidence fields: that is our best single match for the number, selected from those same candidates. Use names when you want to see the full picture behind that decision.

📘

Why are the city, date of birth or address fields empty in my response?

Availability of these details depends on the country of the phone number and on what data exists for it. For some countries we return the name match only, and these fields come back empty or null. Always handle null values on your side.

There is also a second cause: if we cannot determine a name for the number, every list in the response comes back null—including any city, date of birth or address we hold for it. A name match is a precondition for all the other details.