API Documentation

Scrub numbers from your own systems

A small REST API for checking numbers against DNC and honeypot data without going through the web uploader. Requests draw on the same coin balance at the same rates.

Authentication

Create a key under Account → API Keys and send it as a bearer token. Keys are shown once at creation and stored only as a hash, so keep a copy somewhere safe.

Authorization: Bearer cf_live_xxxxxxxxxxxxxxxxxxxxxxxx

Check numbers

POST /api/v1/scrub — up to 1,000 numbers per request.

curl -X POST https://carrierfence.com/api/v1/scrub \
  -H "Authorization: Bearer cf_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["2125551234", "(415) 555-9876", "312-555-0000"],
    "checks": ["dnc", "honeypot"]
  }'

Response:

{
  "status": "completed",
  "coinsCharged": 7.5,
  "balance": 99992.5,
  "checked": 3,
  "dncHits": 1,
  "honeypotHits": 0,
  "results": [
    { "number": "2125551234", "valid": true, "dnc": true,  "honeypot": false, "litigator": false,
      "callTime": { "status": "ok", "label": "OK to call", "state": "NY", "timeZone": "America/New_York",
                    "localTime": "Tue 2:15 PM EDT", "callingHoursToday": "8 AM – 9 PM",
                    "nextAllowed": null, "nextAllowedLocal": null },
      "carrier": "Verizon New York, INC.", "lineType": "Landline" },
    { "number": "4155559876", "valid": true, "dnc": false, "honeypot": false, "litigator": false,
      "callTime": { "status": "early", "label": "Too early", "state": "CA", "timeZone": "America/Los_Angeles",
                    "localTime": "Tue 7:15 AM PDT", "callingHoursToday": "8 AM – 9 PM",
                    "nextAllowed": "2026-10-06T15:00:00.000Z", "nextAllowedLocal": "Tue, Oct 6, 8:00 AM PDT" },
      "carrier": "T-Mobile USA", "lineType": "Mobile" }
  ]
}

Every result includes a free callTime check: whether a telemarketing call is allowed right now in that number's local time (federal 8 AM – 9 PM plus stricter state hours, Sunday and state holiday bans), and if not, the next allowed time. status is one of ok, early, late, closed_day or unknown_area. Each result also has a free carrier and lineType (Mobile, Landline, VoIP or Pager) for the carrier the number was first assigned to; a number moved to another carrier keeps showing the original one. Both are null when unknown.

Numbers are normalised for you — dashes, spaces, brackets and a leading 1 are all accepted. Anything that isn't a valid 10-digit US number comes back with valid: false and isn't charged.

Check your balance

GET /api/v1/balance — free, costs no coins.

curl https://carrierfence.com/api/v1/balance \
  -H "Authorization: Bearer cf_live_xxxxxxxx"

{ "balance": 99992.5, "rates": { "dnc": 1, "honeypot": 1.5 } }

What it costs

Identical to the web uploader. Each valid number costs 1 coin for a DNC check and 1.5 for a honeypot check, so requesting both is 2.5 coins per number. Invalid numbers are free. Duplicates within a request are charged, so de-duplicate your list first if you care about the difference.

Checks requested	Coins per number	1,000 numbers
`["dnc"]`	1	1,000 coins
`["honeypot"]`	1.5	1,500 coins
`["dnc", "honeypot"]`	2.5	2,500 coins

Errors

Status	Error	Meaning
400	`invalid_request`	Missing or empty numbers array, or no valid check requested
400	`too_many_numbers`	More than 1,000 numbers — split into several requests
401	`unauthorized`	Missing, malformed or revoked API key
402	`insufficient_balance`	Not enough coins; response includes how many more are needed

Nothing is charged when a request fails. The debit and the lookup happen in one transaction, so a failure leaves your balance untouched.

Get a key

New accounts start with 500 coins — enough to test the API properly.

Start Free