Number Lookup

A lookup tells you what kind of line a US number is and whether it still works. Dial sessions and single calls run one before every dial. You can also run lookups yourself, one number at a time or in batches of up to 1,000.

What a lookup returns

Field	Type	Description
`phone_number`	string	The number in E.164 format.
`line_type`	string	mobile, landline, voip, toll_free or unknown.
`line_status`	string	active, disconnected or unknown.
`carrier`	object	name and type of the carrier that serves the number.
`caller_name`	string \| null	The caller name on file. Only when caller_name was requested.
`state`	string	Two-letter state from the rate center.
`time_zone`	string	IANA time zone from the rate center.

state and time_zone come from the number's rate center. A mobile number keeps its rate center when its owner moves. Calling hours use the state you send on the lead when you send one.

Before each dial

Every dial starts with a lookup of line type and line status. A disconnected number is never dialed. The lead gets a call.blocked event with reason line_disconnected and no next_allowed_at, and the session moves to the next lead without using a line.

The lookup is one of the pre-dial checks. Lookups before each dial are part of the per-minute rate.

Event

{
  "id": "evt_8Bk40Lq2",
  "type": "call.blocked",
  "created_at": "2026-11-03T15:10:21.004Z",
  "livemode": true,
  "data": {
    "lead_id": "led_44Hc9",
    "phone": "+15125550193",
    "reason": "line_disconnected",
    "rule": "lookup.line_status",
    "next_allowed_at": null
  }
}

Look up one number

A single lookup returns the result in the response. Leave out fields to get everything except caller_name.

POST/v1/lookups

Parameters	Type	Description
`phone_number`required	string	The number in E.164 format.
`fields`	string[]	Any of line_type, line_status, carrier, caller_name. Default all except caller_name.

POST/v1/lookups

curl https://api.liveleg.dev/v1/lookups \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+17205550126",
    "fields": [
      "line_type",
      "line_status",
      "carrier",
      "caller_name"
    ]
  }'

const res = await fetch('https://api.liveleg.dev/v1/lookups', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone_number: "+17205550126",
    fields: [
      "line_type",
      "line_status",
      "carrier",
      "caller_name"
    ]
  }),
});
const data = await res.json();

import os, requests

data = requests.post(
    "https://api.liveleg.dev/v1/lookups",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    json={
        "phone_number": "+17205550126",
        "fields": ["line_type", "line_status", "carrier", "caller_name"],
    },
).json()

Response

{
  "id": "lkp_7Qe20Ma",
  "object": "lookup",
  "phone_number": "+17205550126",
  "line_type": "mobile",
  "line_status": "active",
  "carrier": {
    "name": "Example Wireless",
    "type": "wireless"
  },
  "caller_name": "HOLLIS FAMILY DENTAL",
  "state": "CO",
  "time_zone": "America/Denver",
  "created_at": "2026-11-03T15:02:11Z"
}

Look up a list

Send up to 1,000 numbers in one batch. The batch runs in the background. lookup.batch_completed arrives when it is done, and the results are on the batch.

POST/v1/lookups/batches

POST/v1/lookups/batches

curl https://api.liveleg.dev/v1/lookups/batches \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": [
      "+15125550147",
      "+15125550163",
      "+15125550193"
    ],
    "fields": [
      "line_type",
      "line_status"
    ]
  }'

const res = await fetch('https://api.liveleg.dev/v1/lookups/batches', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone_numbers: [
      "+15125550147",
      "+15125550163",
      "+15125550193"
    ],
    fields: [
      "line_type",
      "line_status"
    ]
  }),
});
const data = await res.json();

import os, requests

data = requests.post(
    "https://api.liveleg.dev/v1/lookups/batches",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    json={
        "phone_numbers": ["+15125550147", "+15125550163", "+15125550193"],
        "fields": ["line_type", "line_status"],
    },
).json()

Event

{
  "id": "evt_5Ld02Rc7",
  "type": "lookup.batch_completed",
  "created_at": "2026-11-03T15:04:52.310Z",
  "livemode": true,
  "data": {
    "batch_id": "lkb_3Hd81Ka",
    "count": 3,
    "disconnected": 1
  }
}

GET/v1/lookups/batches/{id}

GET/v1/lookups/batches/lkb_3Hd81Ka

curl https://api.liveleg.dev/v1/lookups/batches/lkb_3Hd81Ka \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/lookups/batches/lkb_3Hd81Ka', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const data = await res.json();

import os, requests

data = requests.get(
    "https://api.liveleg.dev/v1/lookups/batches/lkb_3Hd81Ka",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
).json()

Response

{
  "id": "lkb_3Hd81Ka",
  "object": "lookup_batch",
  "status": "completed",
  "count": 3,
  "results": [
    {
      "phone_number": "+15125550147",
      "line_type": "mobile",
      "line_status": "active"
    },
    {
      "phone_number": "+15125550163",
      "line_type": "landline",
      "line_status": "active"
    },
    {
      "phone_number": "+15125550193",
      "line_type": "unknown",
      "line_status": "disconnected"
    }
  ],
  "created_at": "2026-11-03T15:04:40Z",
  "completed_at": "2026-11-03T15:04:52Z"
}

Use the results

Remove numbers with line_status disconnected when you import a list.
Send texts to mobile numbers. Landlines cannot receive them.
Use caller_name to check the business behind a number before an agent calls it.
A number with line_status unknown is still dialed. The check before each dial runs again at that time.

Every field and endpoint is listed in the Lookups API reference.