| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
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": "39349xxxxxxx"
}'Here's a detailed explanation of all fields needed for the api call:
| name | type |
|---|---|
| transaction_id | string A unique identifier for the transaction. Duplicate values are not allowed. Ex: 4115d9d9-28f4-4100-8701-cafe2adbc4c2 |
| phone_number | string The phone number to analyze, in international format. Ex: 39349xxxxxxx |
Response
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": "Via Gustavo Fara, 9",
"count": 2
}
],
"names_with_addresses": [
{
"first_name": "Tony",
"last_name": "Stark",
"value": "Via Gustavo Fara, 9",
"count": 2
}
],
"country_code": "GB"
}Here's a detailed explanation of all fields returned:
| name | type |
|---|---|
| is_valid_format | boolean Indicates if the phone number you provided has a valid format Ex: true |
| first_name | ?string When detected, it indicates the first name associated to the phone number Ex: John |
| last_name | ?string When detected, it indicates the last name associated to the phone number Ex: Doe |
| confidence | ?string When detected, it indicates the level of confidence of detected name Ex: LOW, MEDIUM or HIGH |
| has_phone_to_name_match | ?boolean Indicates if at least one name has been found associated with the provided phone number. Ex: trueoolean** |
| names | ?object[] names is a list of objects that contains all names detected from different sources. The object contains the following fields:
|
| names_cities | ?object[] names_cities is a list of objects that contains all names and cities detected from different sources. The object contains the following fields:
|
| cities | ?object[] cities is a list of cities found for the number, aggregated by occurrence and not associated to a specific name. The object contains the following fields:
|
| names_dobs | ?object[] names_dobs is a list of objects that contains all dates of birth detected from different sources. The object contains the following fields:
|
| names_with_dobs | ?object[] names_with_dobs is a list of objects pairing a name with a date of birth. The object contains the following fields:
|
| names_addresses | ?object[] names_addresses is a list of objects that contains all addresses detected from different sources. The object contains the following fields:
|
| names_with_addresses | ?object[] names_with_addresses is a list of objects pairing a name with a postal address. The object contains the following fields:
|
FAQ
Following are some common questions for this specific API:
Why do 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 happen 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 will only include the is_valid_format field (false)—charged at the same rate as a standard API call.