Lookups

A lookup returns the line type, carrier and line status of a US number, and the caller name on file if you ask for it. Dial sessions run a lookup before every dial on their own. Use this resource to check numbers yourself, for example when you import a list.

Guide: Number Lookup.

Endpoints

POST	`/v1/lookups`	Look up a number
POST	`/v1/lookups/batches`	Look up a batch
GET	`/v1/lookups/batches/{id}`	Retrieve a batch

The lookup object

Field	Type	Description
`id`	string	Unique ID, starts with lkp_.
`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.
`created_at`	string	When the lookup ran, ISO 8601.

Look up a number

Runs a lookup and returns the result right away.

POST/v1/lookups

Body 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 batch

Looks up up to 1,000 numbers. The batch runs in the background and lookup.batch_completed is sent when it is done.

POST/v1/lookups/batches

Body parameters	Type	Description
`phone_numbers`required	string[]	Up to 1,000 numbers in E.164 format.
`fields`	string[]	Same as for a single lookup.

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

Response

{
  "id": "lkb_3Hd81Ka",
  "object": "lookup_batch",
  "status": "processing",
  "count": 3,
  "created_at": "2026-11-03T15:04:40Z"
}

Retrieve a batch

Returns the batch status and, when it is done, the results.

GET/v1/lookups/batches/{id}

GET/v1/lookups/batches/{id}

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"
}