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.

1curl -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 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

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

Property	Description
`CallerName`	A string indicating the name of the owner of the phone number. If not available, this will be `null`.
`CallerType`	A string indicating whether this caller is a business or consumer. Possible values are `BUSINESS` and `CONSUMER`. If not available, this will be `null`.
`ErrorCode`	The error code, if any, associated with your request.

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();

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}