Caller Name

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

Coverage

Caller Name is only available for phone numbers owned by carriers in the United States. The data is sourced from CNAM.

(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.

Run Caller Name

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

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

Response properties

A Caller Name request returns the following properties.

Property	Description
`CallerName`	The name of the owner of the phone number. If not available, this will be `null`.
`CallerType`	The caller type. Possible values are `BUSINESS` and `CONSUMER`. If not available, this will be `null`.
`ErrorCode`	The error code, if any, associated with your request.

Code examples and responses

Caller Name Lookup

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async 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
18fetchPhoneNumber();

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}