Telephony and contact center

Check carriers, phone numbers and phone complaints in Twilio

Screen a US number before your Twilio code sends to it: see the carrier the number block was first assigned to, its state and rate center, and whether the block is in service.

Why the data matters in Twilio

Apps built on Twilio tend to take numbers straight from a signup form, so malformed input, blocks that are not assigned and numbers in the wrong country all become failed sends, error callbacks and a log full of undelivered rows. Checking the number in your own code, before the API call, keeps those out.

What LookValid checks

LookValid checks for Twilio
Product	What it does here	Credits
Carrier Lookup (original carrier)	Returns the carrier originally assigned a US number block, with its state, rate center and whether the block is in service. It does not reflect a number that was moved to another carrier.	1 credit per lookup (numbers outside the covered numbering plan areas are free)
Phone Numbering-Plan Validation	Checks the number against its numbering plan and returns the E.164 form your send call expects, plus the type the plan assigns it.	1 credit per valid number
Phone Spam Check	Returns public consumer complaint counts for a number, useful before you call back a number that showed up on an inbound log.	1 credit per number with complaints on record
Country Calling Codes	Describes a country calling code, its national number lengths and example numbers, for sign-up forms that take international numbers.	1 credit per lookup (an unknown code, country or name is free)

Connect it in four steps

Create your LookValid account first, then issue a key from the API keys area.
Add the key as an Environment Variable named LOOKVALID_API_KEY in the Settings of your Functions Service (with the Serverless Toolkit, in its .env file instead), and read it from context.LOOKVALID_API_KEY inside the Function.
Call the carrier lookup endpoint with the destination number before you send; on found:false hold the send for review, and on an error answer stop and log the returned code.
Store numberState and numberRateCenter next to the destination number and skip the send when blockInService comes back false.

A Twilio Function (Node.js, edited in the Functions Editor or deployed with the Serverless Toolkit) or a route in your own Node service, called before the code that sends a message or places a call. The call is POST https://YOUR_API_HOST/v1/carrier-lookup and costs 1 credit per lookup (numbers outside the covered numbering plan areas are free).

screenTwilioNumber.mjs

1const API_URL = "https://YOUR_API_HOST/v1/carrier-lookup";
2
3export async function screenTwilioNumber(value) {
4  const response = await fetch(API_URL, {
5    method: "POST",
6    headers: {
7      Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
8      "Content-Type": "application/json",
9    },
10    body: JSON.stringify({
11      "phone": value,
12    }),
13  });
14  const result = await response.json();
15  if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
16  if (!result.found) return null;
17  return {
18      "numberState": result.data?.state ?? null,
19      "numberRateCenter": result.data?.rate_center ?? null,
20      "blockInService": result.data?.in_service ?? null,
21  };
22}

Where each response field goes in Twilio
Response field	Goes into
data.state	numberState
data.rate_center	numberRateCenter
data.in_service	blockInService

The recipe returns nothing when the lookup finds nothing, which costs no credits for this product, and stops with the error code and fix on a failed request.

Without code

If your messages go out from a Studio flow, its Run Function widget can call a Function that makes the lookup. If they go out from an automation platform instead, put a generic HTTP request step in front of the send action. It posts the destination number to the carrier lookup endpoint with your key in the Authorization header, and a condition on the in-service field decides whether the send step runs. No dedicated app is involved, only the URL, one header and a small JSON body.

REST and MCPOne shared credit balance

Questions

What is the price of a number check before a Twilio send?

Each lookup costs the credits shown on the pricing page. That is separate from anything you pay for the send itself.

Does it cover numbers outside the United States?

The carrier lookup covers US number blocks only; Canada and the Caribbean are not included. The phone check works for numbers worldwide but reads the numbering plan, not a carrier.

Where do I keep the key next to my Twilio credentials?

As its own Environment Variable in the Functions Service, which Twilio stores encrypted. Keep it apart from the account SID and auth token values so you can change each one on its own.

Sources

Twilio documentation: Functions https://www.twilio.com/docs/serverless/functions-assets/functions, read 2026-10-18
Twilio documentation: Environment Variables for Functions https://www.twilio.com/docs/serverless/functions-assets/functions/variables, read 2026-10-18
LookValid API reference: Carrier Lookup (original carrier) https://lookvalid.com/docs/api/carrier-lookup, read 2026-10-18

LookValid is run by Meralume Labs. It is not connected to, endorsed by or a partner of any company or product named on this page, and every product name belongs to its owner.

LookValid bills every lookup in credits from one shared balance, so the same key works for each check above.

See Carrier Lookup (original carrier)