Number reputation

Number reputation registers your numbers, checks each one for spam labels every day, and rests, cleans or replaces any number that gets labeled. Turn it on per caller ID pool.

What it includes

Registration of each number and your business with the US call analytics engines before the first call.
Caller name (CNAM), the business name shown on landlines and many mobiles.
Branded caller ID, your name and logo on supported mobile phones, after your business is verified.
A daily check of every number for spam labels, plus the answer rate per number.
Daily call caps and resting across the pool.
Spam cleaning, and a replacement number when a label is not cleared.

Every call is signed for STIR/SHAKEN at no charge. It is part of every call, with or without number reputation. See Caller ID.

Number reputationDaily spam label monitoring, caller name (CNAM), branded caller ID, registration with the call analytics engines, daily caps, resting and replacement.	$3/ number / month
Spam cleaningDispute with the analytics engines, re-registration, rest and recheck. Free replacement number if the label is not cleared within 14 days.	$50/ number, one time

Read the health of a number

Each number has a state and a label status. label_status is clean, labeled or blocked. A sharp drop in answer rate on one number compared with the rest of the pool also triggers a check.

GET/v1/numbers/{id}/health

GET/v1/numbers/num_5Tq81/health

curl https://api.liveleg.dev/v1/numbers/num_5Tq81/health \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/numbers/num_5Tq81/health', {
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const health = await res.json();

import os, requests

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

Response

{
  "number_id": "num_5Tq81",
  "phone_number": "+15125550199",
  "state": "active",
  "label_status": "clean",
  "labels": [],
  "caller_name": "RIDGELINE ROOF",
  "branded_caller_id": "approved",
  "calls_today": 41,
  "daily_call_cap": 100,
  "answer_rate_7d": 0.138,
  "pool_answer_rate_7d": 0.141,
  "rest_until": null,
  "cleaning_status": null,
  "last_checked_at": "2026-11-03T11:00:04Z"
}

Field	Type	Description
`state`	string	active, resting, callbacks_only or retired. See the table below.
`label_status`	string	clean, labeled or blocked. blocked means a carrier is rejecting calls from the number.
`labels`	array	Each label found, with engine, label and first_seen_at.
`caller_name`	string	The caller name (CNAM) on file for the number.
`branded_caller_id`	string	pending, approved, rejected or not_registered.
`calls_today`	integer	Outbound calls today in the number's own time zone.
`daily_call_cap`	integer	The cap set on the pool.
`answer_rate_7d`	number	Share of calls from this number answered by a person over 7 days.
`pool_answer_rate_7d`	number	The same rate for the whole pool, to compare against.
`rest_until`	string	When a resting number dials out again.
`cleaning_status`	string	The spam cleaning status, when cleaning is running.
`last_checked_at`	string	The time of the last label check.

State	Meaning
`active`	Dials out and takes calls.
`resting`	Takes no outbound calls for a set time, then comes back. Callbacks still ring through.
`callbacks_only`	Only takes calls. Used while spam cleaning runs.
`retired`	Replaced or released. No longer used for calls.

What happens when a number is labeled

A labeled number stops dialing out the same day, and the pool's policy decides what comes next. Callbacks to the number keep ringing through in every case.

rest rests the number for rest_days, then checks it again.
clean starts spam cleaning.
replace retires the number and buys a new one in the same area code. Leads who saw the old number get the new one. Callbacks to the retired number keep reaching you for 90 days.
notify sends the event and leaves the number dialing.

PATCH/v1/caller_id_pools/pool_local_presence

curl -X PATCH https://api.liveleg.dev/v1/caller_id_pools/pool_local_presence \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -d reputation=true \
  -d on_label=clean \
  -d rest_days=7

const res = await fetch('https://api.liveleg.dev/v1/caller_id_pools/pool_local_presence', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ reputation: true, on_label: 'clean', rest_days: 7 }),
});
const pool = await res.json();

import os, requests

pool = requests.patch(
    "https://api.liveleg.dev/v1/caller_id_pools/pool_local_presence",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    json={"reputation": True, "on_label": "clean", "rest_days": 7},
).json()

Event

{
  "id": "evt_9Lp22Wm4",
  "type": "number.health_changed",
  "created_at": "2026-11-04T11:00:12.551Z",
  "livemode": true,
  "data": {
    "number_id": "num_5Tq81",
    "phone_number": "+15125550199",
    "previous": "clean",
    "current": "labeled",
    "labels": [{"engine": "engine_b", "label": "spam_likely"}],
    "action_taken": "cleaning_started",
    "policy": "clean"
  }
}

Spam cleaning

Spam cleaning files a dispute with each engine that shows a label, registers the number again, rests it and checks it until the label is gone. If the label is not cleared within 14 days, we replace the number at no charge. Start it by hand or set on_label=clean on the pool. Each cleaning is billed once per number at the spam cleaning price above.

POST/v1/numbers/{id}/cleaning

POST/v1/numbers/num_5Tq81/cleaning

curl -X POST https://api.liveleg.dev/v1/numbers/num_5Tq81/cleaning \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/numbers/num_5Tq81/cleaning', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const cleaning = await res.json();

import os, requests

cleaning = requests.post(
    "https://api.liveleg.dev/v1/numbers/num_5Tq81/cleaning",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
).json()

Response

{
  "id": "cln_7Rw20",
  "object": "number_cleaning",
  "number_id": "num_5Tq81",
  "phone_number": "+15125550199",
  "status": "filed",
  "engines": [
    {"engine": "engine_b", "label": "spam_likely", "status": "filed"}
  ],
  "filed_at": "2026-11-04T11:00:15Z",
  "replace_after": "2026-11-18T11:00:15Z",
  "replacement_number_id": null
}

Read the current cleaning with GET /v1/numbers/{id}/cleaning. replace_after is the end of the 14 days.

Status	Meaning
`filed`	A dispute is filed with each engine that shows a label. The number is in callbacks_only.
`in_progress`	The number is registered again, resting and checked every day.
`cleared`	No engine shows a label. The number returns to active and dials out again.
`replaced`	The label was not cleared within 14 days. The number is retired and a new one in the same area code takes its place at no charge.

While cleaning runs, the number takes no outbound calls and callbacks still ring through. On replaced, leads who saw the old number get the new one from then on, and callbacks to the old number keep reaching you for 90 days. number.cleaning_updated reports each status, and number.state_changed reports the number's state.

Event

{
  "id": "evt_4Tz18Hq0",
  "type": "number.cleaning_updated",
  "created_at": "2026-11-18T11:00:20.104Z",
  "livemode": true,
  "data": {
    "number_id": "num_5Tq81",
    "status": "replaced",
    "engines": [{"engine": "engine_b", "label": "spam_likely", "status": "not_cleared"}],
    "replacement_number_id": "num_8Bv42"
  }
}

Free Caller Registry

The Free Caller Registry must be filed by the business that makes the calls. We prepare the filing and the numbers file, and you submit it. Each new number is added to the next filing. Number reputation also registers your numbers with the call analytics engines.