Skip to content
numberalive Get started
API

Dashboard or API. Same engine.

One call in, one answer out. Send a number, get back the options you asked for. Use it at the form, in the dialer, in your CRM. Every API lookup also lands in your dashboard contacts, so nothing lives only in a log.

Get a key

Create a key on the API page of your dashboard. The full key is shown once, when you create it. You can have several keys and revoke any of them at any time. Keys start with na_live_.

Get started

Basics

Base URL: https://numberalive.com/api/v1. HTTPS only. Every answer is JSON.

Send your key as a bearer token on every request.

Authorization: Bearer YOUR_API_KEY

A success answers {"request_id": "...", "data": {...}}. A failure answers {"request_id": "...", "error": {"type": "...", "code": "...", "message": "..."}}. The same request id is in the X-Request-Id header: quote it when you contact support. Keep your key on your server: browsers cannot call the API directly, because it sends no cross-origin headers.

Look up one number

GET or POST /lookup. Send phone plus the options you want, as a query string, a form or a JSON object. Choose at least one option. A parameter that is not phone or an option name is refused, so a typo never costs credits.

curl https://numberalive.com/api/v1/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d phone=2125550100 -d remove_landline=1 -d append_carrier=1
{
  "request_id": "req_4f35c64731bbde24803bcfdf",
  "data": {
    "input": "2125550100",
    "phone": "2125550100",
    "keep": true,
    "reasons": [],
    "unchecked": [],
    "fields": {"carrier": "Example Wireless", "carrier_ocn": ""},
    "credits_used": 1,
    "balance": 4999
  }
}
  • keep: true when none of the options you chose removes the number.
  • reasons: why it is removed, each with a code and a label. Empty when kept.
  • unchecked: chosen options this number could not be judged by. The number stays, and you can see it was not checked.
  • fields: the data your append_ options add. Only what you chose is returned.
  • phone: the ten digits we looked up, or null when the input is not a valid US or Canadian number. An invalid number answers 200 with the reason invalid and costs nothing.
  • credits_used and balance: what the call cost and what is left.

A removed number looks like this:

{
  "request_id": "req_93a15b2070e3e89c0e554a1b",
  "data": {
    "input": "2125550101",
    "phone": "2125550101",
    "keep": false,
    "reasons": [{"code": "landline", "label": "Landline"}],
    "unchecked": [],
    "fields": {"carrier": "Example Telephone", "carrier_ocn": ""},
    "credits_used": 1,
    "balance": 4998
  }
}

Look up up to 1,000 numbers

POST /lookup/bulk with a JSON body: phones, a list of up to 1,000 numbers, and options, an object of option names and true or false. More than 1,000 is a 400. Results come back in the order you sent them, one per number. A number repeated in the list is looked up and charged once, and each copy gets the same answer.

curl https://numberalive.com/api/v1/lookup/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["2125550100", "(212) 555-0101", "2125550102", "12345"],
       "options": {"remove_landline": true, "remove_litigators": true, "append_carrier": true}}'
{
  "request_id": "req_ff25f5f39b8a3f18b6866ed6",
  "data": {
    "results": [
      {"input": "2125550100", "phone": "2125550100", "keep": true, "reasons": [], "unchecked": [],
       "fields": {"carrier": "Example Wireless", "carrier_ocn": ""}},
      {"input": "(212) 555-0101", "phone": "2125550101", "keep": false,
       "reasons": [{"code": "landline", "label": "Landline"}], "unchecked": [],
       "fields": {"carrier": "Example Telephone", "carrier_ocn": ""}},
      {"input": "2125550102", "phone": "2125550102", "keep": false,
       "reasons": [{"code": "litigator", "label": "Known litigator"}], "unchecked": [],
       "fields": {"carrier": "", "carrier_ocn": ""}},
      {"input": "12345", "phone": null, "keep": false,
       "reasons": [{"code": "invalid", "label": "Not a valid US or Canadian number"}], "unchecked": [],
       "fields": {}}
    ],
    "totals": {
      "total": 4, "kept": 1, "removed": 3,
      "removed_by_reason": {"litigator": 1, "landline": 1, "invalid": 1},
      "invalid": 1, "duplicates": 0, "errors": 0, "unchecked": {}
    },
    "credits_used": 6,
    "balance": 4992
  }
}

A number that could not be checked comes back removed with the reason error ("Could not be verified"). It is not charged and is not added to your contacts: send it again later. If none of the numbers could be checked, the call fails with a 502 or 503 instead.

Check your balance

GET /credits

curl https://numberalive.com/api/v1/credits -H "Authorization: Bearer YOUR_API_KEY"

{"request_id": "req_8fdffa06858f296ddfcad0a4", "data": {"balance": 4992}}

Options

The same options as the dashboard, named exactly as below. In /lookup they are top-level parameters; in /lookup/bulk they go in options. Accepted values: true, 1, yes, on and false, 0, no, off.

  • remove_landline: Remove landlines.
  • keep_sms_landlines: Keep landlines that can receive texts. Needs remove_landline. Has its own credit rate, see pricing.
  • remove_voip: Remove VoIP numbers.
  • remove_deactivated: Remove deactivated and suspended numbers.
  • remove_blacklisted: Remove blacklisted numbers.
  • remove_duplicates: Remove duplicates.
  • remove_litigators: Remove known litigators. Has its own credit rate, see pricing.
  • remove_dnc_state: Remove state do-not-call numbers. Has its own credit rate, see pricing.
  • remove_dnc_complainers: Remove known do-not-call complainers. Has its own credit rate, see pricing.
  • append_carrier: Add carrier. Adds carrier, carrier_ocn to fields.
  • append_line_type: Add line type. Adds line_type, line_subtype to fields.
  • append_port: Add port info. Adds ported, port_date to fields.
  • append_timezone: Add time zone. Adds timezone, tz_offset to fields.
  • append_geo: Add location. Adds state, city, metro, geo_source to fields.
  • append_age: Add number age. Adds age_days to fields.
  • append_clicker: Add clicker flag. Adds clicker to fields.

Reason codes

A removed number lists every reason that applies, most serious first.

  • litigator: Known litigator
  • dnc_complainer: Known do-not-call complainer
  • dnc_state: On a state do-not-call list
  • blacklisted: Blacklisted
  • deactivated: Deactivated or suspended
  • landline: Landline
  • voip: VoIP
  • duplicate: Duplicate
  • invalid: Not a valid US or Canadian number
  • error: Could not be verified

Credits and retries

Credits are prepaid and the balance never goes below zero. Each looked-up number costs a base lookup plus the options that have their own rate: see pricing for what a credit costs and what each option adds. Invalid numbers, repeats and numbers that could not be checked are free.

  • Before it looks anything up, a call is checked against your balance. If the balance is below the least the call can cost, it answers 402 with your balance and the credits_needed, and nothing is looked up.
  • You are charged for what the call actually used, in one ledger entry.
  • If the final cost is more than your balance (for example another call spent credits at the same time), the call answers 402, nothing is charged and no contact is saved. Add credits and send it again.
  • Send an Idempotency-Key header to make a retry safe. The same key with the same request is charged once, however many times it is sent, and the repeat answers with the header Idempotent-Replayed: true. The same key with a different request is a new charge.

Errors

The HTTP status says what kind of failure it is; the error's code says exactly which.

  • 400: The request is not valid: a missing or unknown parameter, an option that needs another option, a body that is not JSON, or more than 1,000 numbers.
  • 401: The key is missing, malformed, wrong or revoked.
  • 402: Not enough credits. The error holds your balance and the credits needed.
  • 404: No endpoint at that path.
  • 405: The method is not allowed on that endpoint. The Allow header lists the ones that are.
  • 429: Too many requests. Wait the number of seconds in the Retry-After header.
  • 500: Something went wrong on our side. Nothing was charged for a call that ended this way.
  • 502: The lookup could not be completed. Nothing was charged. Try again.
  • 503: The lookup service is temporarily unavailable. Nothing was charged. Try again after the Retry-After header.
{
  "request_id": "req_0cecbbd68647292c81404824",
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "Not enough credits for this request. Nothing was charged.",
    "balance": 1,
    "credits_needed": 2
  }
}

Rate limits

Each key can make 300 requests in any 60 seconds. Over that, a call answers 429 with a Retry-After header, and the calls that were refused do not count against the limit. Requests with a bad key count against the caller's address: after 20 in 15 minutes that address is refused for a while. For many numbers, use the bulk endpoint rather than many single calls.