API reference / Phone and calls

Phone number reputation

A number that people have reported as an unwanted caller is a poor number to send from. This route tells you how many complaints the FCC has on file for each number you ask about. It works for any US or Canadian number, whether you own it or not, so you can screen a number before you buy it or load it, and re-check the ones you already use.

Routes

Method	Route	Scope	What it does
`POST`	`/phone/public/numbers/reputation`	`numbers:read`	Check 1 to 100 numbers

Check numbers

Send phone_numbers, an array of 1 to 100 numbers. Use E.164 (+12025550143) or the national format people type ((202) 555-0143, read as US).

curl -X POST https://api-v2.dropcowboy.com/phone/public/numbers/reputation \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "phone_numbers": ["+12025550143", "(415) 555-0192"] }'

{
  "data": {
    "results": [
      {
        "phone_number": "+12025550143",
        "input": "+12025550143",
        "status": "ok",
        "fcc": { "complaints_total": 7, "complaints_last_12_months": 2 },
        "checked_at": "2026-10-12T14:03:21.482Z",
        "cached": false
      },
      {
        "phone_number": "+14155550192",
        "input": "(415) 555-0192",
        "status": "ok",
        "fcc": { "complaints_total": 0, "complaints_last_12_months": 0 },
        "checked_at": "2026-10-12T09:41:08.115Z",
        "cached": true
      }
    ],
    "charge": { "amount": 0.002, "currency": "USD", "numbers_billed": 2 }
  },
  "meta": { "request_id": "5d0c7b1e-3a42-4f6a-9e8b-2c1f7a9d4e30" }
}

results has one entry per number you sent, in the order you sent them. input is the entry as you wrote it, and phone_number is the same number in E.164.

`status`	Meaning	What to do
`ok`	The number was checked. `fcc` holds the counts.	Read `complaints_last_12_months` first: it tells you whether people are reporting the number now.
`invalid`	The entry isn't a phone number. `phone_number` is `null`.	Fix the entry and send it again.
`unsupported`	A valid number outside the US and Canada, which the FCC doesn't cover.	Nothing to check for this number.

complaints_total counts every complaint on file. A count of 0 means the FCC has no complaint that names the number as the caller ID. Carriers and call-labeling apps use other signals too, so 0 doesn't tell you how they treat the number.

The FCC publishes its complaints once a day, and we keep each answer for 12 hours. checked_at is when the data was read and cached is true when the answer came from that 12-hour store. Checking the same number again within 12 hours returns the same counts.

Price

Each distinct number that is checked costs $0.001, taken from your prepaid balance. A different rate applies if your account has its own. The charge in the response shows what the request cost.

An answer from the 12-hour store costs the same as a fresh one.
invalid and unsupported entries cost nothing, and a number repeated in one request is billed once.
A refused or failed request costs nothing.
Accounts still on a trial get 402. Add funds to your account first.

Limits

Each request holds at most 100 numbers, and each account can send 30 requests a minute. Past that you get 429 with a Retry-After header: wait that many seconds, then retry.

Errors

Status	Cause	What to do
`400`	`phone_numbers` is missing, empty, holds more than 100 entries, or has an entry that isn't a non-empty string.	Fix the request.
`402`	A trial account, a past-due subscription, or a balance too low for the numbers in the request.	Add funds or update your payment method, then retry.
`429`	More than 30 requests in a minute.	Wait `Retry-After` seconds.
`502`	The lookup could not be completed. Nothing was charged.	Retry.

The envelope and the error format are in Responses, errors and limits.