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.

Caller Name Lookup

1curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/%2B14159929960?Fields=caller_name" \
2-u $TWILIO_API_KEY:$TWILIO_API_SECRET

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 at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function fetchPhoneNumber() {
14  const phoneNumber = await client.lookups.v2
15    .phoneNumbers("+14159929960")
16    .fetch({ fields: "caller_name" });
17
18  console.log(phoneNumber.callerName);
19}
20
21fetchPhoneNumber();

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}