Skip to contentSkip to navigationSkip to topbar
On this page

Caller Name


Lookup's Caller Name allows you to get information on the caller name and type for a mobile phone number.

Caller Name Lookups are billed per Lookup, even if data is not available. Currently, requesting a Caller Name Lookup for international numbers will return null values, but will not be billed.

To make a Caller Name request, add caller_name to the optional query parameter Fields when making a standard Lookup request.

1
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}?Fields=caller_name" \ -u
2
$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Coverage and Limitations: Data is sourced by CNAM(link takes you to an external page) and is only available for phone numbers owned by carriers in the US.

Release Stage and Access: General access (GA), available via self-service.


Response properties

response-properties page anchor

The following additional properties are returned for a Caller Name request.

PropertyDescription
CallerNameA string indicating the name of the owner of the phone number. If not available, this will be null.
CallerTypeA string indicating whether this caller is a business or consumer. Possible values are BUSINESS and CONSUMER. If not available, this will be null.
ErrorCodeThe error code, if any, associated with your request.
Caller Name LookupLink to code sample: Caller Name Lookup
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchPhoneNumber() {
11
const phoneNumber = await client.lookups.v2
12
.phoneNumbers("+14159929960")
13
.fetch({ fields: "caller_name" });
14
15
console.log(phoneNumber.callerName);
16
}
17
18
fetchPhoneNumber();

Output

1
{
2
"calling_country_code": "1",
3
"country_code": "US",
4
"phone_number": "+14159929960",
5
"national_format": "(415) 992-9960",
6
"valid": true,
7
"validation_errors": null,
8
"caller_name": {
9
"caller_name": "Sergio Suarez",
10
"caller_type": "CONSUMER",
11
"error_code": null
12
},
13
"sim_swap": null,
14
"call_forwarding": null,
15
"line_status": null,
16
"line_type_intelligence": null,
17
"identity_match": null,
18
"reassigned_number": null,
19
"sms_pumping_risk": null,
20
"phone_number_quality_score": null,
21
"pre_fill": null,
22
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960"
23
}

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.