Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Caller Name

Use Caller Name to retrieve the caller's name and type (business or consumer) for a mobile phone number.

Coverage

coverage page anchor

Caller Name is only available for phone numbers owned by carriers in the United States. The data is sourced from CNAM(link takes you to an external page).

(information)

Info

Caller Name is billed per request, even if no data is returned. Requests for phone numbers outside the US will return null but won't be charged. For additional pricing information, contact Sales(link takes you to an external page).

Run Caller Name

run-caller-name page anchor

Make a GET /v2/PhoneNumbers/{PhoneNumber} request with the Fields=caller_name query parameter.

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

2
$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response properties

response-properties page anchor

A Caller Name request returns the following properties.

PropertyDescription
CallerNameThe name of the owner of the phone number. If not available, this will be null.
CallerTypeThe caller type. Possible values are BUSINESS and CONSUMER. If not available, this will be null.
ErrorCodeThe error code, if any, associated with your request.

Code examples and responses

code-examples-and-responses page anchor
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();

Response

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
}