Looking Up Carrier Information for a Number

The carrier lookup endpoint returns the mobile carrier behind a phone number (MDN). Use it to validate that a number is a reachable mobile line, to make routing decisions, or as a pre-send check before you spend a message segment on a number that can't receive SMS.

When to use it

• Before sending — confirm a number is a mobile line, not a landline or an invalid number.
• Routing — branch your own logic on the carrier serving a number.
• List hygiene — clean inbound lead lists by dropping numbers that don't resolve to a supported carrier.

Pre-flight checklist

The API call

The number goes in the path and must be URL-encoded — the leading + becomes %2B. So +13125551212 is sent as %2B13125551212:

curl https://api.otterblocx.com/messaging/carrier/%2B13125551212 \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY"

Response (200 OK):

{
  "mdn": "+13125551212",
  "carrier": "104",
  "carrierName": "AT&T"
}

carrierName is the human-readable carrier (e.g. AT&T, Verizon Wireless, T-Mobile); carrier is the underlying numeric code. mdn echoes back the number in E.164 form. For numbers on a carrier we can't map, carrierName is null while carrier still carries the code.

Full reference: api.otterblocx.com/docs.

Using the SDK

The SDK handles the URL encoding for you — pass the plain E.164 number:

import { createBlocxClient, Messaging } from '@otterlabs/blocx'

const { client } = createBlocxClient({
  accessKeyId: process.env.BLOCX_ACCESS_KEY_ID!,
  secretAccessKey: process.env.BLOCX_SECRET_ACCESS_KEY!,
})

const res = await Messaging.getCarrierInfo({
  client,
  path: { mdn: '+13125551212' },
})

console.log(res.data?.carrierName) // "AT&T"

Install: npm install @otterlabs/blocx. Source on npm: @otterlabs/blocx.

Rate limits

Carrier lookups are limited to 25 requests per minute per account by default. Every response includes the standard headers so you can pace your calls:

Going over the limit returns 429 Too Many Requests.

Need more than 25/min?

There's no fixed ceiling — the default is just a starting point. On the Quotas page, click Request increase next to Carrier lookups / min and tell us the throughput you need. Routine increases are typically approved the same business day. See Understanding Quotas and Usage for the full process.

Errors

Related articles

• Sending Your First SMS
• Understanding Quotas and Usage
• Managing API Keys