Skip to content
ProofTell
Sign inSign up
Contents
ProofTell API · 1.0.0

API reference

One call to assess the fraud risk of a phone number, email address and IP address — and each signal on its own. Version 1: new fields, endpoints and error codes may appear at any time, so ignore what you do not know; a documented endpoint or field is removed or renamed only after the notice the terms of service give (60 days, §6). Money is a decimal string in USD, never a float: six places for a call's cost and per-run prices (exact at every step of the volume curve), four for balances, two per 1,000.

Base URL
https://api.prooftell.com
Format
JSON in, JSON out. Money is a decimal string in USD, never a float: six places for a call’s cost and per-run prices, four for balances.
Keys
Created in the dashboard: pt_live_ for real calls, pt_test_ for the sandbox.

Authentication

Authorization: Bearer pt_live_…, or pt_test_… for sandbox calls (simulated, free). Keys are created in the dashboard. A missing, unknown or revoked key gets 401 invalid_api_key.

Browser calls are supported: /v1/* answers any origin (CORS Access-Control-Allow-Origin: *, without credentials), so a page can read every answer. But a key in a web page can be read by anyone who opens it: keep a pt_live_ key on your server and call from there; a pt_test_ key in a page is fine.

curl https://api.prooftell.com/v1/balance \
  -H "Authorization: Bearer pt_live_…"

Errors

Every error is a JSON body with a stable code and a readable message; some carry more, such as retry_after or the amounts to top up. Codes are stable, messages are not.

Stable. 400: bad_request, unknown_field, invalid_field, invalid_phone, invalid_country, invalid_level, invalid_email, invalid_timeout, invalid_ip, invalid_reference, invalid_name, unreadable_file. 401: invalid_api_key. 402: insufficient_balance. 403: test_organization (a staging key used on this server), production_key (on staging, api.prooftell.dev, only: a key of a production organization, live or sandbox — it works on api.prooftell.com), payment_disputed (a card payment of the account is disputed: the phone levels current_carrier, line_status and fraud_score are refused to every organization of it until it is resolved; basic and line_type still run), staging_restricted (on staging, api.prooftell.dev, only: live checks — /v1/phone, /v1/email, /v1/ip, /v1/assess and running a file — are for ProofTell's team; use a pt_test_ key there), organization_suspended (any call with a key of an organization whose account is suspended under the terms of service, §11, or of a closed organization until its keys are revoked: write to support@prooftell.com). 404: not_found. 409: conflict, unreadable_file. 413: too_large. 429: rate_limited (any route with a key: 20 requests a second per key on each server instance, bursts of 50 — an approximate ceiling, not a quota; too many of the organization's requests at once, retry_after 1; also a client sending many unknown keys). 501: sandbox_not_available. 503: signals_unavailable, files_unavailable, unavailable (a service ProofTell depends on did not answer: retry). 500: internal.

{
  "error": {
    "code": "insufficient_balance",
    "message": "Top up to run this signal.",
    "cost_required": "0.002500",
    "cost_available": "0.000000",
    "cost_missing": "0.002500",
    "topup_url": "https://app.prooftell.com/billing"
  }
}

Sandbox

A pt_test_ key turns every signal endpoint into a sandbox: results are simulated and deterministic, no signal source is called, nothing is billed, and an assessment answers with mode: test. Any input works; each endpoint documents the inputs that produce specific results, so you can build and test your integration, an unavailable signal included, before a real key is involved. Files need a live key. The response samples on this page are real answers: the sandbox’s own to the request beside them, where the call has a sandbox (that request then carries a pt_test_key), and otherwise one the api gave a live key. The dashboard’s Lookups page runs the same calls from a form, sandbox or live, shows each one as cURL, and lists the stored assessments below.

Assess

POST/v1/assess

Assess the risk of an identity

Send any mix of phone, email and IP. Each signal runs in parallel; a supplied signal that cannot run (its source unavailable, or not offered) is reported, never guessed; one not supplied is absent from the answer.

When a supplied signal is unavailable — its source down or past its time budget, or the signal not offered right now (its line says reason: not_offered) — the score comes from the signals that ran, the missing one adds a 0-point reason signal_unavailable_<signal>, and the verdict is raised to at least review (an organization setting can turn the raise off). When none of the supplied signals ran, the call fails with 503 signals_unavailable.

The call costs the signals that returned a result, each at the step of the volume curve your account's month has reached for that signal (curve on /v1/pricing; cost, currency, and a line per signal); unavailable signals cost nothing. The same rules as /v1/phone apply when the balance cannot cover the call: the 402 names its whole price.

With a pt_test_ key the call is a sandbox: results are simulated and deterministic, no signal is called, nothing is billed, and mode is test. Any input works, and every documented reason can be reached: phones +15005550001 (valid mobile), +15005550002 (VoIP), +15005550003 (not valid), +15005550004 (signal unavailable), +15005550007 (toll-free), +15005550008 (unknown line type), any other number with the country of its dialling code (+447700900123 with the US sandbox IP is a geo_mismatch; a national number is read in country, as with a live key); emails <name>@sandbox.prooftell.com with <name> one of deliverable, undeliverable, disposable, catchall, greylisted, risky, role, unavailable; IPs 203.0.113.1 (clean, US), 203.0.113.66 (Tor), 203.0.113.77 (VPN), 203.0.113.99 (datacenter), 203.0.113.4 (unavailable).

Rate limit: 20 requests a second per key on each server instance, bursts of 50 (429 rate_limited): an approximate ceiling against runaway clients, not a quota — with several instances serving, a key may get more through.

Request body

FieldTypeDescription
phonestringE.164 preferred; national format needs country. Up to 32 characters. Example +447700900123.
emailstringAny text: one that is not an address is scored (email_invalid), not refused. Up to 254 characters. Example jane@example.com.
ipstringIPv4 or IPv6 of the end user. Example 203.0.113.1.
countrystringISO 3166-1 alpha-2 hint for national-format phones. Example GB.
referencestringYour own id for this check, echoed back. Up to 128 characters.

Responses

curl -X POST https://api.prooftell.com/v1/assess \
  -H "Authorization: Bearer pt_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+447700900123",
  "email": "jane@example.com",
  "ip": "203.0.113.1",
  "country": "GB"
}'
{
  "id": "asm_4ceu7cr3cm7nah6r",
  "mode": "test",
  "score": 15,
  "verdict": "allow",
  "reasons": [
    {
      "code": "geo_mismatch",
      "points": 15,
      "message": "The phone number's country (GB) differs from the IP address's (US)."
    }
  ],
  "signals": {
    "phone": {
      "status": "ok",
      "cost": "0.000000",
      "result": {
        "status": "success",
        "phone": "+447700900123",
        "valid": true,
        "line_type": "mobile",
        "region": "Sandbox",
        "country": "United Kingdom",
        "country_code": "GB",
        "country_prefix": "44",
        "international_format": "+44 7700 900123",
        "national_format": "07700 900123",
        "e164": "+447700900123",
        "original_carrier": "Sandbox Wireless",
        "timezone": [
          "Europe/London"
        ],
        "geographical": false
      }
    },
    "email": {
      "status": "ok",
      "cost": "0.000000",
      "result": {
        "status": "success",
        "email": "jane@example.com",
        "result": "deliverable",
        "deliverable": true,
        "did_you_mean": "",
        "user": "jane",
        "domain": "example.com",
        "code": 200,
        "verdict": "deliverable",
        "reason": "mailbox_exists",
        "suggested_action": "accept",
        "flags": {
          "disposable": false,
          "role_account": false,
          "free_provider": false,
          "catch_all": false
        },
        "provider": "",
        "latency_ms": 12
      }
    },
    "ip": {
      "status": "ok",
      "cost": "0.000000",
      "result": {
        "ip": "203.0.113.1",
        "status": "success",
        "version": 4,
        "routable": true,
        "country_code": "US",
        "country": "United States",
        "region": "New York",
        "city": "Sandbox City",
        "latitude": 40.7128,
        "longitude": -74.006,
        "accuracy_km": 20,
        "timezone": "America/New_York",
        "asn": 64500,
        "as_org": "SANDBOX-NET",
        "is_tor": false,
        "is_vpn": false,
        "is_datacenter": false,
        "is_anonymous": false,
        "anycast": false,
        "data_version": "sandbox"
      }
    }
  },
  "ruleset": "2026-10-07",
  "cost": "0.000000",
  "currency": "USD",
  "createdAt": "2026-10-27T15:59:50.195198859Z"
}
The sandbox's answer to the request shown: a GB number and a US address, a geo_mismatch.

Signals

POST/v1/phone

Look up a phone number

A phone lookup in five levels, each including the ones before it (level, default line_type):

  • basic — free: whether the number is valid, its E.164, international and national formats, its country and calling code. No line type, no carrier.
  • line_type — plus the line type (mobile, fixed line, VoIP, toll-free, premium-rate…), the carrier the range was allocated to (original_carrier), the region and the time zone, from the numbering plan. Charged when status is success; a number that could not be parsed is answered and free.
  • current_carrier — plus the carrier the number is on today and whether it was ported (current_carrier).
  • line_status — plus whether the subscriber is on the network right now and, when not, why — switched off, absent, unknown subscriber… (line_status, an HLR lookup; current_carrier is filled from the same network answer).
  • fraud_score — plus the number's fraud intelligence: validity against the regulator's allocated ranges, the range's service type (premium-rate, satellite, VoIP, M2M…), IPRN and MSRN flags with dates, a 0–100 score with its risk_level (fraud_score; current_carrier and line_status are filled from the same answer, presence without the reason detail).

Charged from your balance at the step of the volume curve your account's month has reached for each line (curve on /v1/pricing: the list for a month's first 10,000 checks of a signal, less past them; cost says what this call cost). Without balance a call fails with 402 insufficient_balance and the amounts to top up — basic too: it costs nothing, but like every live call it needs a balance. There is no free quota; the sandbox is the free path.

The levels above line type are provider-backed: they need balance, are priced per country band (/v1/pricing), and the call's cost is the line type's line plus the level's line, each charged on its own outcome. Where ProofTell does not offer a level — for the number's country, or at all yet — its line says unavailable with not_offered or not_offered_in_country, costs nothing, and the line type's answer still comes back. When nothing can run, the call fails with 503.

Line status where it reaches. The presence check reaches some mobile networks and not others; the dashboard's Coverage page lists them by country and carrier. In a country where it reaches none — the United States among them — a line_status request is answered from the current carrier. On a network it does not reach — or a fixed line — the presence check names the network but not the subscriber's state. Either way the answer carries the current_carrier block and a line_status block with covered: false and reason: network_not_covered (fixed_line for a fixed line), the line_status line is unavailable with that reason and costs nothing, and the current_carrier line carries the charge: the call costs line type plus current carrier, never line status. When the check can name only the network the number was issued to, current_carrier has that as original_carrier (no carrier, no ported) and the call costs line type only. Where the current carrier level is not offered (for the number's country, or at all), its line is unavailable with that reason, the answer carries no current_carrier block and no network, and the call costs line type only.

Fraud score without presence. Where the fraud score cannot query presence, line_status comes back with reason: presence_not_available and the call is charged for what came back: the current_carrier line (when the carrier the number is on today is known — the United States, for one) plus the fraud_score line at the rate of the score alone (phone_fraud_score_only on /v1/pricing), the line_status line unavailable at no cost. When portability is not available either, current_carrier is unavailable with portability_not_available, the network known is under current_carrier.original_carrier, and the call costs line type plus the score alone — as it does when the current carrier level is not offered for the number: then its line says so, and the answer carries no current_carrier block and no network.

With a pt_test_ key the call is a sandbox: the result is simulated and deterministic, no signal is called, nothing is billed, and the answer carries every field a live one has. A level your organization is not offered answers as it does with a live key: its line unavailable with not_offered, no block. Any number works and its country follows the dialling code (+447700900123 is a GB mobile); a national number is read in country, as with a live key (07700 900123 with GB is that mobile). +15005550001 is a valid mobile, +15005550002 VoIP (fraud score: medium), +15005550003 not valid (status: success, valid: false, reason: unrecognized_range), +15005550004 answers 503 as an unavailable signal would, +15005550006 a premium-rate IPRN (line type: premium_rate; fraud score: high), +15005550007 toll-free, +15005550008 a line of unknown type and +15005550009 a ported number (current carrier: on another carrier). The sandbox follows the coverage: a US number at line_status gets the uncovered answer, as with a live key. +447700900005 is switched off (line status: not present), and +447700900010 is on a network line status does not reach. +442079460000 is a fixed line (line status: fixed_line; fraud score: presence_not_available), and +447700900011 is on a network with no portability data (line status: only current_carrier.original_carrier, charged as line type; fraud score: presence_not_available, the current_carrier line unavailable with portability_not_available). At basic no number is magic: the check is the api's own, computed for any number as with a live key.

Request body

FieldTypeDescription
phonerequiredstringE.164 preferred; national format needs country. Up to 32 characters. Example +447700900123.
countrystringISO 3166-1 alpha-2 hint for national-format phones. Example GB.
levelstringHow far to look; each level includes the ones before it. line_type when omitted. One of basic, line_type, current_carrier, line_status, fraud_score. Example line_status.

Responses

curl -X POST https://api.prooftell.com/v1/phone \
  -H "Authorization: Bearer pt_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+447700900123",
  "country": "GB",
  "level": "line_status"
}'
{
  "status": "success",
  "phone": "+447700900123",
  "valid": true,
  "line_type": "mobile",
  "region": "Sandbox",
  "country": "United Kingdom",
  "country_code": "GB",
  "country_prefix": "44",
  "international_format": "+44 7700 900123",
  "national_format": "07700 900123",
  "e164": "+447700900123",
  "original_carrier": "Sandbox Wireless",
  "timezone": [
    "Europe/London"
  ],
  "geographical": false,
  "level": "line_status",
  "line_status": {
    "status": "success",
    "present": "yes",
    "reachable": true,
    "covered": true,
    "ported": false,
    "network": "Sandbox Wireless",
    "line_type": "mobile",
    "country_code": "GB"
  },
  "current_carrier": {
    "status": "success",
    "carrier": "Sandbox Wireless",
    "ported": false,
    "country_code": "GB",
    "source": "line_status"
  },
  "cost": "0.000000",
  "currency": "USD",
  "signals": {
    "line_type": {
      "status": "ok",
      "cost": "0.000000"
    },
    "line_status": {
      "status": "ok",
      "cost": "0.000000"
    }
  }
}
The sandbox's answer to the request shown: +447700900123 at line_status, present on its network. A live answer has the same fields; this number, from a range the UK keeps for drama, is not valid with a live key.
POST/v1/email

Verify an email address

The email check on its own: the response is the verification's own JSON — status, result, verdict, reason, billed, suggested_action, flags and the rest — plus cost, currency and signals. A run is charged exactly when its billed is true: syntax errors, unknowns and softbounces are free.

Same rules as /v1/phone when the balance cannot cover a run. timeout (milliseconds, at most 45000) bounds the SMTP dialogue; past it the address comes back unknown, free.

With a pt_test_ key the call is a sandbox, simulated and free, in the live check's own vocabulary — its four verdicts (deliverable, undeliverable, risky, unknown), its reason names and codes, billed, suggested_action and flags. Any address is deliverable (mailbox_exists); <name>@sandbox.prooftell.com with <name> one of undeliverable (hardbounce, mailbox_rejected), disposable (risky, disposable_domain), catchall (risky, domain_catch_all), greylisted (unknown, softbounce, free), risky (inbox_full, mailbox_full) or role (deliverable, with flags.role_account) gives that result; unavailable answers 503.

Request body

FieldTypeDescription
emailrequiredstringUp to 254 characters. Example jane@example.com.
timeoutintegerThe budget for the SMTP dialogue, milliseconds (45 s at most). 1000 to 45000.

Responses

curl -X POST https://api.prooftell.com/v1/email \
  -H "Authorization: Bearer pt_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "jane@example.com"
}'
{
  "status": "success",
  "email": "jane@example.com",
  "result": "deliverable",
  "deliverable": true,
  "did_you_mean": "",
  "user": "jane",
  "domain": "example.com",
  "code": 200,
  "verdict": "deliverable",
  "reason": "mailbox_exists",
  "billed": true,
  "suggested_action": "accept",
  "flags": {
    "disposable": false,
    "role_account": false,
    "free_provider": false,
    "catch_all": false
  },
  "provider": "",
  "latency_ms": 12,
  "cost": "0.000000",
  "currency": "USD",
  "signals": {
    "email": {
      "status": "ok",
      "cost": "0.000000"
    }
  }
}
The sandbox's answer to the request shown: an address other than the documented ones is deliverable.
POST/v1/ip

Look up an IP address

ProofTell's own IP intelligence: geography and network from GeoLite2, plus open Tor, VPN and datacenter lists — all in ProofTell's infrastructure, the address never leaves. Charged when the address parsed and was looked up; a private or reserved address is answered (routable: false) and free. Same rules as /v1/phone when the balance cannot cover a run.

With a pt_test_ key the call is a sandbox, simulated and free: 203.0.113.1 is clean, 203.0.113.66 Tor, 203.0.113.77 VPN, 203.0.113.99 datacenter and 203.0.113.4 answers 503.

Request body

FieldTypeDescription
iprequiredstringIPv4 or IPv6. Example 203.0.113.66.

Responses

  • 200The address, its geography, its network and the list flags, plus the billing fields. Body: IpResult.
  • 400An Error body.
  • 401An Error body.
  • 402An Error body.
  • 403An Error body.
  • 429An Error body.
  • 500An Error body.
  • 503An Error body.
curl -X POST https://api.prooftell.com/v1/ip \
  -H "Authorization: Bearer pt_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "ip": "203.0.113.66"
}'
{
  "ip": "203.0.113.66",
  "status": "success",
  "version": 4,
  "routable": true,
  "country_code": "US",
  "country": "United States",
  "region": "New York",
  "city": "Sandbox City",
  "latitude": 40.7128,
  "longitude": -74.006,
  "accuracy_km": 20,
  "timezone": "America/New_York",
  "asn": 64500,
  "as_org": "SANDBOX-NET",
  "is_tor": true,
  "is_vpn": false,
  "is_datacenter": true,
  "is_anonymous": true,
  "anycast": false,
  "data_version": "sandbox",
  "cost": "0.000000",
  "currency": "USD",
  "signals": {
    "ip": {
      "status": "ok",
      "cost": "0.000000"
    }
  }
}
The sandbox's answer for its documented Tor address. With a live key, an address of this documentation range is routable: false, free.

Files

GET/v1/files

Your organization's 100 newest files

The organization's 100 newest files, newest first. There is no paging: an older file is still reached by its id (GET /v1/files/{fileId}) until it expires, 30 days after upload.

Responses

curl https://api.prooftell.com/v1/files \
  -H "Authorization: Bearer pt_live_…"
[
  {
    "id": "fil_k2m9q7x3a8b4c5d6",
    "name": "leads.csv",
    "status": "verifying",
    "stage": "queued",
    "format": {
      "bom": false,
      "encoding": "UTF-8",
      "kind": "csv",
      "lenient": false,
      "delimiter": ","
    },
    "columns": {
      "email": 1,
      "phone": 2,
      "ip": -1,
      "header_row": true
    },
    "rows": 3,
    "unique_rows": 2,
    "signals": [
      "phone_line_type"
    ],
    "country": "MA",
    "hold": "0.0050",
    "charged": "0.0000",
    "counters": {},
    "error": null,
    "created_at": "2026-10-27T09:12:44.512031Z",
    "expires_at": "2026-11-26T09:12:44.512031Z"
  }
]
A live key's answer: one file, running.
POST/v1/files

Start a file job

Two ways in. Signed upload (up to 1 GB and 5 million rows; an XLSX up to 50 MB): send JSON {name, content_type}; the answer carries upload_url and headers — PUT the bytes there with exactly those headers (the URL accepts one upload of at most 1 GB, for 12 hours), then call finish. Direct upload (up to 32 MB): send the bytes as multipart/form-data field file; analysis runs at once and the answer is the analysed job. A request body over 32 MB is refused with a 413 by the platform before it reaches the api, without a JSON body: use the signed upload for larger files. Upload and analysis are free. CSV, TSV, TXT (one value per line) and XLSX. Files need a live key: with a pt_test_ key every /v1/files call answers 501 sandbox_not_available.

Request bodyapplication/json · multipart/form-data

FieldTypeDescription
namerequiredstringUp to 200 characters. Example leads.csv.
content_typestringExample text/csv.

Responses

curl -X POST https://api.prooftell.com/v1/files \
  -H "Authorization: Bearer pt_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "leads.csv",
  "content_type": "text/csv"
}'
{
  "file": {
    "id": "fil_k2m9q7x3a8b4c5d6",
    "name": "leads.csv",
    "status": "uploading",
    "stage": "upload",
    "format": null,
    "columns": null,
    "rows": 0,
    "unique_rows": 0,
    "signals": [],
    "country": null,
    "hold": "0.0000",
    "charged": "0.0000",
    "counters": {},
    "error": null,
    "created_at": "2026-10-27T09:12:44.512031Z",
    "expires_at": "2026-11-26T09:12:44.512031Z"
  },
  "headers": {
    "x-goog-if-generation-match": "0",
    "Content-Type": "text/csv",
    "x-goog-content-length-range": "0,1073741824"
  },
  "upload_url": "https://storage.googleapis.com/prooftell-files/orgs/org_7d2kq9x4m3b8p6tz/files/fil_k2m9q7x3a8b4c5d6/source?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=…&X-Goog-Date=20261027T091244Z&X-Goog-Expires=43200&X-Goog-SignedHeaders=content-type%3Bhost%3Bx-goog-content-length-range%3Bx-goog-if-generation-match&X-Goog-Signature=…"
}
The signed upload's answer to the request shown (the URL shortened here).
GET/v1/files/{fileId}

A file job and its progress

Parameters

FieldTypeDescription
fileIdrequiredstring · pathExample fil_k2m9q7x3a8b4c5d6.

Responses

curl https://api.prooftell.com/v1/files/fil_k2m9q7x3a8b4c5d6 \
  -H "Authorization: Bearer pt_live_…"
{
  "id": "fil_k2m9q7x3a8b4c5d6",
  "name": "leads.csv",
  "status": "verifying",
  "stage": "queued",
  "format": {
    "bom": false,
    "encoding": "UTF-8",
    "kind": "csv",
    "lenient": false,
    "delimiter": ","
  },
  "columns": {
    "email": 1,
    "phone": 2,
    "ip": -1,
    "header_row": true
  },
  "rows": 3,
  "unique_rows": 2,
  "signals": [
    "phone_line_type"
  ],
  "country": "MA",
  "hold": "0.0050",
  "charged": "0.0000",
  "counters": {},
  "error": null,
  "created_at": "2026-10-27T09:12:44.512031Z",
  "expires_at": "2026-11-26T09:12:44.512031Z",
  "header": [
    "name",
    "email",
    "phone"
  ],
  "samples": [
    [
      "Ann",
      "ann@example.com",
      "0612345678"
    ],
    [
      "Bob",
      "bob@example.com",
      "+447400123456"
    ],
    [
      "Ann",
      "ann@example.com",
      "0612345678"
    ]
  ]
}
A running file.
DELETE/v1/files/{fileId}

Delete a file job and its objects

Parameters

FieldTypeDescription
fileIdrequiredstring · pathExample fil_k2m9q7x3a8b4c5d6.

Responses

curl -X DELETE https://api.prooftell.com/v1/files/fil_k2m9q7x3a8b4c5d6 \
  -H "Authorization: Bearer pt_live_…"
POST/v1/files/{fileId}/finish

The signed upload landed — analyse it

Parameters

FieldTypeDescription
fileIdrequiredstring · pathExample fil_k2m9q7x3a8b4c5d6.

Responses

curl -X POST https://api.prooftell.com/v1/files/fil_k2m9q7x3a8b4c5d6/finish \
  -H "Authorization: Bearer pt_live_…"
{
  "id": "fil_k2m9q7x3a8b4c5d6",
  "name": "leads.csv",
  "status": "ready",
  "stage": "ready",
  "format": {
    "bom": false,
    "encoding": "UTF-8",
    "kind": "csv",
    "lenient": false,
    "delimiter": ","
  },
  "columns": {
    "email": 1,
    "phone": 2,
    "ip": -1,
    "header_row": true
  },
  "rows": 3,
  "unique_rows": 0,
  "signals": [],
  "country": null,
  "hold": "0.0000",
  "charged": "0.0000",
  "counters": {},
  "error": null,
  "created_at": "2026-10-27T09:12:44.512031Z",
  "expires_at": "2026-11-26T09:12:44.512031Z",
  "header": [
    "name",
    "email",
    "phone"
  ],
  "samples": [
    [
      "Ann",
      "ann@example.com",
      "0612345678"
    ],
    [
      "Bob",
      "bob@example.com",
      "+447400123456"
    ],
    [
      "Ann",
      "ann@example.com",
      "0612345678"
    ]
  ]
}
The analysed file: its format, the columns found, the first rows.
POST/v1/files/{fileId}/verify

Run the file

Holds what the file's unique rows cost per selected signal on your balance — priced down the volume curve from the step your account's month has reached for that signal (curve on /v1/pricing), the dearest country bands at the dearest steps — (402 insufficient_balance with the amounts when it cannot cover it), then runs. Rows are charged as they complete, at the step each reaches, against the hold, and what is left of it is released at the end; duplicates run once and are flagged in pt_duplicate_of; rows a source could not judge are free. columns overrides the detected mapping (0-based; -1 = none). country reads the phone column's national numbers in that country (0612345678 with MA); a number written with its country code keeps it. Without country, give numbers in E.164; a country that is not an ISO 3166-1 alpha-2 code with a numbering plan is 400 bad_request.

The phone column runs at one level (signals: phone_line_type, or phone_current_carrier, phone_line_status or phone_fraud_score; basic is by API only), priced as /v1/phone prices it: the line type's line plus the level's at each number's country band, held with the dearest bands first. A level needs to be offered to your organization (400 otherwise) and no disputed card payment on the account (403 payment_disputed); a number no numbering plan knows runs line type only, its level line free, and a country where the level is not served answers not_offered_in_country for that row, free.

Parameters

FieldTypeDescription
fileIdrequiredstring · pathExample fil_k2m9q7x3a8b4c5d6.

Request body

FieldTypeDescription
signalsrequiredarray of stringWhat to run on the mapped columns: one phone entry — phone_line_type, or a level, phone_current_carrier, phone_line_status or phone_fraud_score, each including the ones before it — and email, ip.
columnsFileColumns
countrystring | nullISO 3166-1 alpha-2, for the phone column's numbers in national format; absent, null or blank, none. A code without a numbering plan is 400 bad_request. Example MA.

Responses

curl -X POST https://api.prooftell.com/v1/files/fil_k2m9q7x3a8b4c5d6/verify \
  -H "Authorization: Bearer pt_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "signals": [
    "phone_line_type"
  ],
  "country": "MA"
}'
{
  "id": "fil_k2m9q7x3a8b4c5d6",
  "name": "leads.csv",
  "status": "verifying",
  "stage": "queued",
  "format": {
    "bom": false,
    "encoding": "UTF-8",
    "kind": "csv",
    "lenient": false,
    "delimiter": ","
  },
  "columns": {
    "email": 1,
    "phone": 2,
    "ip": -1,
    "header_row": true
  },
  "rows": 3,
  "unique_rows": 2,
  "signals": [
    "phone_line_type"
  ],
  "country": "MA",
  "hold": "0.0050",
  "charged": "0.0000",
  "counters": {},
  "error": null,
  "created_at": "2026-10-27T09:12:44.512031Z",
  "expires_at": "2026-11-26T09:12:44.512031Z"
}
The answer to the request shown: two unique numbers, held at line type.
POST/v1/files/{fileId}/stop

Stop a running file

Parameters

FieldTypeDescription
fileIdrequiredstring · pathExample fil_k2m9q7x3a8b4c5d6.

Responses

curl -X POST https://api.prooftell.com/v1/files/fil_k2m9q7x3a8b4c5d6/stop \
  -H "Authorization: Bearer pt_live_…"
GET/v1/files/{fileId}/download

A 15-minute link to the result

Parameters

FieldTypeDescription
fileIdrequiredstring · pathExample fil_k2m9q7x3a8b4c5d6.
whichstring · queryresult: the CSV result; xlsx: the result as a workbook, for an XLSX upload only (409 for any other); source: the file as uploaded. Another value is 400. One of result, xlsx, source. Default result.

Responses

  • 200The link (result is a CSV in the upload's own delimiter; while running, a partial result with unreached rows pending, for files of up to 250,000 rows — 409 above)
  • 400An Error body.
  • 401An Error body.
  • 403An Error body.
  • 404An Error body.
  • 409An Error body.
  • 429An Error body.
  • 500An Error body.
  • 501An Error body.
  • 503An Error body.
FieldTypeDescription
urlrequiredstring (uri)
curl https://api.prooftell.com/v1/files/fil_k2m9q7x3a8b4c5d6/download \
  -H "Authorization: Bearer pt_live_…"
{
  "url": "https://storage.googleapis.com/prooftell-files/orgs/org_7d2kq9x4m3b8p6tz/files/fil_k2m9q7x3a8b4c5d6/partial-1793116790327.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=…&X-Goog-Date=20261027T091244Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=…"
}
A 15-minute signed link (shortened here).

Account

GET/v1/pricingPublic

The rate card

Public. One price list for everyone: the rate of every signal per run and per 1,000 (the list, what a month's first 10,000 checks of a signal cost), its volume tiers — each check of a signal prices at the tier the account's month has reached, per the curve —, country bands for banded signals, the top-up amounts, the minimum top-up and the monthly amounts. Cached for five minutes. The website, the dashboard and the docs all read prices from here.

Responses

curl https://api.prooftell.com/v1/pricing
{
  "version": "2026-10-24",
  "currency": "USD",
  "services": [
    {
      "service": "phone_basic",
      "label": "Phone intelligence, basic",
      "per_run": "0.000000",
      "per_1000": "0.00",
      "tiers": [
        {
          "upto": null,
          "per_run": "0.000000",
          "per_1000": "0.00"
        }
      ]
    },
    {
      "service": "phone_line_type",
      "label": "Phone intelligence, line type",
      "per_run": "0.002500",
      "per_1000": "2.50",
      "tiers": [
        {
          "upto": 10000,
          "per_run": "0.002500",
          "per_1000": "2.50"
        },
        {
          "upto": 50000,
          "per_run": "0.001750",
          "per_1000": "1.75"
        },
        {
          "upto": 250000,
          "per_run": "0.001125",
          "per_1000": "1.13"
        },
        {
          "upto": 1000000,
          "per_run": "0.000750",
          "per_1000": "0.75"
        },
        {
          "upto": null,
          "per_run": "0.000500",
          "per_1000": "0.50"
        }
      ]
    },
    {
      "service": "phone_current_carrier",
      "label": "Phone intelligence, current carrier",
      "bands": {
        "default": {
          "per_run": "0.005500",
          "per_1000": "5.50",
          "tiers": [
            {
              "upto": 10000,
              "per_run": "0.005500",
              "per_1000": "5.50"
            },
            {
              "upto": 50000,
              "per_run": "0.003850",
              "per_1000": "3.85"
            },
            {
              "upto": 250000,
              "per_run": "0.002475",
              "per_1000": "2.48"
            },
            {
              "upto": null,
              "per_run": "0.001650",
              "per_1000": "1.65"
            }
          ],
          "countries": []
        }
      }
    },
    {
      "service": "phone_line_status",
      "label": "Phone intelligence, line status",
      "bands": {
        "default": {
          "per_run": "0.013500",
          "per_1000": "13.50",
          "tiers": [
            {
              "upto": 10000,
              "per_run": "0.013500",
              "per_1000": "13.50"
            },
            {
              "upto": 50000,
              "per_run": "0.009450",
              "per_1000": "9.45"
            },
            {
              "upto": 250000,
              "per_run": "0.006075",
              "per_1000": "6.08"
            },
            {
              "upto": null,
              "per_run": "0.004050",
              "per_1000": "4.05"
            }
          ],
          "countries": []
        }
      }
    },
    {
      "service": "email",
      "label": "Email verification",
      "per_run": "0.004000",
      "per_1000": "4.00",
      "tiers": [
        {
          "upto": 10000,
          "per_run": "0.004000",
          "per_1000": "4.00"
        },
        {
          "upto": 50000,
          "per_run": "0.002800",
          "per_1000": "2.80"
        },
        {
          "upto": 250000,
          "per_run": "0.001800",
          "per_1000": "1.80"
        },
        {
          "upto": 1000000,
          "per_run": "0.001200",
          "per_1000": "1.20"
        },
        {
          "upto": null,
          "per_run": "0.000800",
          "per_1000": "0.80"
        }
      ]
    },
    {
      "service": "ip",
      "label": "IP intelligence",
      "per_run": "0.000500",
      "per_1000": "0.50",
      "tiers": [
        {
          "upto": 10000,
          "per_run": "0.000500",
          "per_1000": "0.50"
        },
        {
          "upto": 50000,
          "per_run": "0.000350",
          "per_1000": "0.35"
        },
        {
          "upto": 250000,
          "per_run": "0.000225",
          "per_1000": "0.23"
        },
        {
          "upto": 1000000,
          "per_run": "0.000150",
          "per_1000": "0.15"
        },
        {
          "upto": null,
          "per_run": "0.000100",
          "per_1000": "0.10"
        }
      ]
    }
  ],
  "curve": [
    {
      "upto": 10000,
      "multiplier": 1
    },
    {
      "upto": 50000,
      "multiplier": 0.7
    },
    {
      "upto": 250000,
      "multiplier": 0.45
    },
    {
      "upto": 1000000,
      "multiplier": 0.3
    },
    {
      "upto": null,
      "multiplier": 0.2
    }
  ],
  "min_topup": "10.00",
  "topup_amounts": [
    "100.00",
    "500.00",
    "1000.00",
    "5000.00"
  ],
  "subscription_amounts": [
    "50.00",
    "100.00",
    "250.00",
    "500.00"
  ]
}
The rate card today.
GET/v1/balance

Your account's balance

Balance — paid and promotional money, held amounts, in dollars to four places — and what this month's runs cost so far, across the account: the organizations of an account share one balance, so every key of the account answers the same figures, whichever organization it belongs to.

Responses

curl https://api.prooftell.com/v1/balance \
  -H "Authorization: Bearer pt_live_…"
{
  "currency": "USD",
  "balance": "124.0000",
  "paid": "126.4000",
  "promotional": "0.0000",
  "held": "2.4000",
  "usage": {
    "month": "2026-10",
    "runs": 3550,
    "amount": "12.4000",
    "signals": {
      "phone_line_type": {
        "runs": 2000,
        "amount": "5.0000"
      },
      "phone_current_carrier": {
        "runs": 800,
        "amount": "4.4000"
      },
      "email": {
        "runs": 750,
        "amount": "3.0000"
      }
    }
  }
}
A live key's answer: an account in the middle of a month, a file running.

Objects

PhoneRequest

FieldTypeDescription
phonerequiredstringE.164 preferred; national format needs country. Up to 32 characters. Example +447700900123.
countrystringISO 3166-1 alpha-2 hint for national-format phones. Example GB.
levelstringHow far to look; each level includes the ones before it. line_type when omitted. One of basic, line_type, current_carrier, line_status, fraud_score. Example line_status.

PhoneBaseResult

The phone answer's own fields (also signals.phone.result of an assessment). At basic, status, phone, valid, reason, e164, the two formats and the country fields only — and so above line type when the line type query did not answer (signals.line_type unavailable): the base is then the number's own parse, the basic check's, with no line type and no carrier.

FieldTypeDescription
statusrequiredstringsuccess: the number was judged, valid or not (by the line type query, a charged run); error: it could not be parsed, free; unavailable only inside an assessment, when the signal did not run. One of success, error, unavailable.
phonestringThe E.164 when the number is valid; as sent otherwise.
validrequiredboolean
reasonstringWhy the number is not valid, when it is not (valid: false, status success or error): too short or too long for its numbering plan, a length the plan does not use, a calling code that does not exist, a length the plan allows in no allocated range (unrecognized_range), or not a number at all. One of too_short, too_long, invalid_length, invalid_country_code, unrecognized_range, not_a_number.
line_typestringThe line type: mobile, fixed_line, fixed_line_or_mobile (where the numbering plan does not tell them apart; a United States number is typed from NANPA's records, which tell most apart), voip, toll_free, premium_rate, shared_cost, personal_number, pager, uan, voicemail or unknown. A number that is not valid is unknown, or short_code (with shortcode_cost) or emergency when it is one; empty when it could not be parsed (status: error).
shortcode_coststringWhat calling it costs, with line_type: short_code only. One of toll_free, standard_rate, premium_rate, unknown.
regionstringWhere the number is registered, e.g. San Francisco, CA.
countrystringExample United Kingdom.
country_codestringExample GB.
country_prefixstringThe calling code. Example 44.
international_formatstringExample +44 7700 900123.
national_formatstringExample 07700 900123.
e164stringExample +447700900123.
original_carrierstringThe carrier the number range was allocated to (the carrier today: current_carrier).
timezonearray of string
geographicalboolean

PhoneResult

PhoneBaseResult, plus the blocks of the requested level and the ones below it (current_carrier, line_status, fraud_score), and the ProofTell fields level, cost, currency and signals.

Every field of PhoneBaseResult, and:

FieldTypeDescription
levelrequiredstringThe level requested. signals says which lines answered: a level refused or unavailable keeps its name here, its line says why. One of basic, line_type, current_carrier, line_status, fraud_score.
current_carrierCurrentCarrierResultNumber portability: the carrier the number is on today. At line_status and fraud_score it is read from that level’s network answer (source).
line_statusLineStatusResultNetwork presence (an HLR lookup): whether the subscriber is present on the mobile network right now. At fraud_score it is read from that level’s answer (source), without the reason detail.
fraud_scoreFraudScoreResultFraud intelligence for the number, with the network facts (presence, portability, current carrier) that the lower levels show.
costrequiredstringWhat this call cost, in currency, six decimals: the line type's line plus the level’s line. Example 0.000000.
currencyrequiredstringOne of USD.
signalsrequiredobjectThe level's line, and above line type the line type's line too: ok with its cost, or unavailable with a reason and no cost. An uncovered line_status request adds the current_carrier line, which carries its charge.
↳ basicSignalLine
↳ line_typeSignalLine
↳ current_carrierSignalLine
↳ line_statusSignalLine
↳ fraud_scoreSignalLine

CurrentCarrierResult

Number portability: the carrier the number is on today. At line_status and fraud_score it is read from that level’s network answer (source).

FieldTypeDescription
statusrequiredstringerror with reason: invalid_number when the number could not be queried, free. One of success, error.
carrierstringThe current carrier. Example Orange Romania.
mccstring
mncstring
lrnstringLocal routing number (USA / Canada only).
ocnstringOperating company number (USA / Canada only).
portedboolean
ported_datestringLast known port, when the level carries it (fraud score).
original_carrierobjectThe carrier the number was allocated to, when it was ported — or, without carrier, the only network known for it (a line status answer that could not name the current one).
↳ carrierstring
↳ mccstring
↳ mncstring
↳ ocnstring
line_typestringThe line type on the carrier the number is on today, in the USA and Canada: that of the block its routing number belongs to, in line_type's values (a mobile number moved to a VoIP provider reads voip here and mobile above). Absent elsewhere. Example voip.
country_codestringExample RO.
sourcestringPresent when the block was derived from a higher level’s answer. One of line_status, fraud_score.

LineStatusResult

Network presence (an HLR lookup): whether the subscriber is present on the mobile network right now. At fraud_score it is read from that level’s answer (source), without the reason detail.

FieldTypeDescription
statusrequiredstringerror with reason: invalid_number when the number could not be queried, free. One of success, error.
presentstringunknown when the network is not covered or did not say. One of yes, no, unknown.
reachableboolean | nullpresent as a boolean; null when unknown.
reasonstringWhy not present or unknown: switched_off, unknown_subscriber, absent, call_barred, roaming_not_allowed, network_not_covered, fixed_line, …; presence_not_available at fraud score.
sourcestringPresent when the block was derived from the fraud score's answer. One of fraud_score.
coveredbooleanWhether the network is one the presence check reaches. false: no presence answer (network_not_covered, fixed_line), and the call is charged as current carrier.
portedboolean
networkstringThe current network.
mccstring
mncstring
original_carrierobjectInstead of network, when the check could name only the network the number was issued to (covered: false; the call costs line type only).
↳ carrierstring
↳ mccstring
↳ mncstring
line_typestringOne of mobile, fixed_line.
country_codestringExample GB.

FraudScoreResult

Fraud intelligence for the number, with the network facts (presence, portability, current carrier) that the lower levels show.

FieldTypeDescription
statusrequiredstringerror with reason invalid_number, invalid_number_length or invalid_number_range, free. One of success, error.
reasonstringOn success: presence_not_available when the presence query was not possible for this number (present is unknown; ported is absent too when portability was not possible either); the rest of the answer stands.
presentstringOne of yes, no, unknown.
portedboolean
ported_datestring
networkstringThe current carrier.
mccstring
mncstring
scoreintegerPropensity-for-fraud score: higher is riskier. 0 to 100.
risk_levelstringmedium from 20, high from 50. One of low, medium, high.
service_typestringThe range’s service type: mobile, voip, premium_rate, satellite, machine_to_machine, freephone, geographic, msrn, … Example mobile.
service_type_codeintegerThe numbering range's service type as a code, 1–33 (service_type names it).
line_typestringOne of mobile, fixed_line.
premium_rateboolean
voipboolean
iprnbooleanFlagged as an international premium-rate number used to test access.
iprn_first_seenstring
iprn_last_seenstring
iprn_rangebooleanIn a range flagged for premium-rate fraud (Wangiri, IRSF).
iprn_range_first_seenstring
iprn_range_last_seenstring
msrnbooleanA mobile station roaming number advertised for roaming-call fraud.
msrn_first_seenstring
msrn_last_seenstring
original_networkstring
country_codestringExample GB.

EmailRequest

FieldTypeDescription
emailrequiredstringUp to 254 characters. Example jane@example.com.
timeoutintegerThe budget for the SMTP dialogue, milliseconds (45 s at most). 1000 to 45000.

EmailVerification

The email check's result: the email signal's own fields (also signals.email.result of an assessment, without billed).

FieldTypeDescription
statusrequiredstringunavailable only inside an assessment, when the signal did not run. One of success, error, unavailable.
emailstringAs sent.
resultrequiredstringThe result label: deliverable, undeliverable, hardbounce, softbounce, catch_all, disposable, inbox_full, unknown, syntax_error.
deliverableboolean
did_you_meanstringA likely correction of a misspelt domain, or empty.
userstringThe part before the @.
domainstring
codeintegerThe numeric result code.
verdictrequiredstringOne of deliverable, undeliverable, risky, unknown.
reasonrequiredstringThe verdict’s reason name, e.g. mailbox_exists, mailbox_rejected, disposable_domain, domain_catch_all, greylisted, mailbox_full, missing_at_sign.
billedbooleanWhether this run counted: a run that did not is free.
suggested_actionstringThe safe default for a sign-up form. One of accept, accept_and_confirm, reject.
flagsobject
↳ disposableboolean
↳ role_accountbooleaninfo@, sales@…
↳ free_providerboolean
↳ catch_allboolean
providerstringThe mail provider behind the domain, when known.
latency_msinteger

EmailResult

EmailVerification, plus the three ProofTell fields.

Every field of EmailVerification, and:

FieldTypeDescription
costrequiredstringExample 0.000000.
currencyrequiredstringOne of USD.
signalsrequiredobject
↳ emailSignalLine

Pricing

FieldTypeDescription
versionrequiredstring
currencyrequiredstringOne of USD.
servicesrequiredarray of object
curvearray of objectThe volume curve, one for every signal: a month's checks of a signal, per account, up to upto (exclusive) price at multiplier × the list; the last step has no upto. Each check prices at the tier it lands in, never retroactively.
topup_amountsarray of stringThe amounts offered as buttons; any amount from min_topup is accepted.
min_topuprequiredstringExample 10.00.
subscription_amountsrequiredarray of string

PriceTier

FieldTypeDescription
uptorequiredinteger | nullChecks of the signal this month, exclusive; null above the last boundary.
per_runrequiredstringSix decimals: exact at every step. Example 0.001750.
per_1000requiredstringExample 1.75.

Balance

FieldTypeDescription
currencyrequiredstringOne of USD.
balancerequiredstringpaid + promotional − held: the account's, shared by its organizations Example 124.0000.
paidrequiredstring
promotionalrequiredstring
heldrequiredstringReserved by running files.
usageobjectThis calendar month, UTC, across the account: runs and what they were charged, at the volume curve's steps, in total and per signal (api calls and files alike, every organization of the account).
↳ monthrequiredstringExample 2026-10.
↳ runsrequiredinteger
↳ amountrequiredstringExample 12.4000.
↳ signalsrequiredobject of object

IpRequest

FieldTypeDescription
iprequiredstringIPv4 or IPv6. Example 203.0.113.66.

IpIntelligence

The IP signal's own fields (also signals.ip.result of an assessment).

FieldTypeDescription
statusrequiredstringunavailable only inside an assessment, when the signal did not run. One of success, unavailable.
iprequiredstring
versionrequiredintegerOne of 4, 6.
routablerequiredbooleanFalse for private, loopback, link-local, multicast and other reserved addresses: unique-local (fc00::/7), shared (100.64.0.0/10), benchmarking (198.18.0.0/15), the documentation ranges and 240.0.0.0/4.
country_codestring | nullExample GB.
countrystring | null
regionstring | null
citystring | null
latitudenumber
longitudenumber
accuracy_kminteger
timezonestring
asninteger | nullExample 15169.
as_orgstring | nullExample GOOGLE.
is_torrequiredboolean
is_vpnrequiredboolean
is_datacenterrequiredboolean
is_anonymousrequiredbooleanTor or VPN.
anycastboolean
data_versionstringIdentifies the data set the answer came from.

IpResult

IpIntelligence, plus the three ProofTell fields.

Every field of IpIntelligence, and:

FieldTypeDescription
costrequiredstring
currencyrequiredstringOne of USD.
signalsrequiredobject
↳ ipSignalLine

CreateFile

FieldTypeDescription
namerequiredstringUp to 200 characters. Example leads.csv.
content_typestringExample text/csv.

FileCreated

FieldTypeDescription
filerequiredFileJob
upload_urlstring (uri)Signed flow only.
headersobject of string

FileColumns

FieldTypeDescription
phonerequiredinteger0-based column; -1 = none
emailrequiredinteger
iprequiredinteger
header_rowrequiredboolean

VerifyFileRequest

FieldTypeDescription
signalsrequiredarray of stringWhat to run on the mapped columns: one phone entry — phone_line_type, or a level, phone_current_carrier, phone_line_status or phone_fraud_score, each including the ones before it — and email, ip.
columnsFileColumns
countrystring | nullISO 3166-1 alpha-2, for the phone column's numbers in national format; absent, null or blank, none. A code without a numbering plan is 400 bad_request. Example MA.

FileJob

FieldTypeDescription
idrequiredstring
namerequiredstring
statusrequiredstringOne of uploading, ready, verifying, complete, failed, stopped, expired.
stagestring
formatobject | nullkind csv|tsv|txt|xlsx, delimiter, encoding, sheet
columnsFileColumns | null
headerarray of string
samplesarray of array of string
rowsrequiredinteger
unique_rowsrequiredinteger
signalsrequiredarray of string
countrystring | nullThe default country the file runs with, for its national-format numbers; null for none.
holdrequiredstringDollars held while running.
chargedrequiredstring
countersrequiredobject of integerrows, unique, duplicates, done, unavailable (rows a source could not judge), deferred (rows waiting for a source to answer again, retried later), <signal>_runs.
errorstring | null
created_atrequiredstring (date-time)
expires_atrequiredstring (date-time)Files and results are deleted 30 days after upload.

SignalLine

FieldTypeDescription
statusrequiredstringOne of ok, unavailable.
reasonstringOn unavailable, when known: not_offered, not_offered_in_country; invalid_number on a level's line when the number is in no numbering plan's allocated ranges (it is not sent to the level, free), or when a line_status request answered from the current carrier could not query the number; for line_status, network_not_covered or fixed_line (answered from the current carrier, charged as current carrier), or, at fraud score, presence_not_available; for current_carrier at fraud score, portability_not_available.
costrequiredstringExample 0.000000.

AssessRequest

FieldTypeDescription
phonestringE.164 preferred; national format needs country. Up to 32 characters. Example +447700900123.
emailstringAny text: one that is not an address is scored (email_invalid), not refused. Up to 254 characters. Example jane@example.com.
ipstringIPv4 or IPv6 of the end user. Example 203.0.113.1.
countrystringISO 3166-1 alpha-2 hint for national-format phones. Example GB.
referencestringYour own id for this check, echoed back. Up to 128 characters.

Assessment

FieldTypeDescription
idrequiredstringExample asm_8f3k2m9q.
moderequiredstringtest for sandbox calls made with a pt_test_ key. One of live, test.
referencestring
scorerequiredinteger0 = no risk found, 100 = highest risk. 0 to 100.
verdictrequiredstringScore compared with your organization's thresholds; at least review when a supplied signal was unavailable (unless the organization turned that off). One of allow, review, deny.
reasonsrequiredarray of Reason
signalsrequiredobjectOne entry per supplied signal; result is that signal’s own fields, exactly as its standalone endpoint returns them.
↳ phoneSignal
↳ resultPhoneBaseResultThe phone answer's own fields (also signals.phone.result of an assessment). At basic, status, phone, valid, reason, e164, the two formats and the country fields only — and so above line type when the line type query did not answer (signals.line_type unavailable): the base is then the number's own parse, the basic check's, with no line type and no carrier.
↳ emailSignal
↳ resultEmailVerificationThe email check's result: the email signal's own fields (also signals.email.result of an assessment, without billed).
↳ ipSignal
↳ resultIpIntelligenceThe IP signal's own fields (also signals.ip.result of an assessment).
rulesetrequiredstringVersion of the scoring rules that produced this result. Example 2026-10-07.
costrequiredstringThe sum of the signal lines, six decimals. Example 0.007000.
currencyrequiredstringOne of USD.
createdAtrequiredstring (date-time)

Reason

One rule that added to the score; the score is the sum of the reasons' points, at most 100. The rule set (ruleset) emits these codes, at these points: phone_invalid 40 (not a valid number), phone_voip 20, phone_non_personal 15 (toll-free, premium-rate, shared-cost, UAN or pager), phone_type_unknown 5; email_invalid 40 (not an address), email_undeliverable 40, email_disposable 35, email_catch_all 10, email_risky 10 (a full mailbox), email_unverifiable 5 (the server would not say), email_role_address 5; ip_tor 40, ip_vpn 20, ip_datacenter 15 (one of the three, the first that applies), ip_not_routable 10; geo_mismatch 15 (the phone's country differs from the IP's); signal_unavailable_phone, signal_unavailable_email, signal_unavailable_ip 0 (a supplied signal that did not run). A changed weight is a new rule set version.

FieldTypeDescription
coderequiredstringStable: one of the codes above. Example email_disposable.
pointsrequiredintegerExample 35.
messagerequiredstringA readable sentence; it may change. Example The email address uses a disposable provider..

Signal

FieldTypeDescription
statusrequiredstringOne of ok, unavailable.
reasonstringOn unavailable, when known: not_offered — ProofTell does not offer the signal right now.
costrequiredstringExample 0.002500.
resultrequiredobjectThe signal's own fields (PhoneBaseResult, EmailVerification, IpIntelligence); on unavailable, just status: unavailable.

Error

FieldTypeDescription
errorrequiredobject
↳ coderequiredstringStable. 400: bad_request, unknown_field, invalid_field, invalid_phone, invalid_country, invalid_level, invalid_email, invalid_timeout, invalid_ip, invalid_reference, invalid_name, unreadable_file. 401: invalid_api_key. 402: insufficient_balance. 403: test_organization (a staging key used on this server), production_key (on staging, api.prooftell.dev, only: a key of a production organization, live or sandbox — it works on api.prooftell.com), payment_disputed (a card payment of the account is disputed: the phone levels current_carrier, line_status and fraud_score are refused to every organization of it until it is resolved; basic and line_type still run), staging_restricted (on staging, api.prooftell.dev, only: live checks — /v1/phone, /v1/email, /v1/ip, /v1/assess and running a file — are for ProofTell's team; use a pt_test_ key there), organization_suspended (any call with a key of an organization whose account is suspended under the terms of service, §11, or of a closed organization until its keys are revoked: write to support@prooftell.com). 404: not_found. 409: conflict, unreadable_file. 413: too_large. 429: rate_limited (any route with a key: 20 requests a second per key on each server instance, bursts of 50 — an approximate ceiling, not a quota; too many of the organization's requests at once, retry_after 1; also a client sending many unknown keys). 501: sandbox_not_available. 503: signals_unavailable, files_unavailable, unavailable (a service ProofTell depends on did not answer: retry). 500: internal.
↳ messagerequiredstring
↳ retry_afterintegerSeconds to wait before retrying, on 429 and 503 (also the Retry-After header).
↳ cost_requiredstringOn insufficient_balance: what the call needs available — its whole price at your account's steps of the volume curve, every line of it, whichever line the balance could not cover (a file: its hold); at basic, which is free but needs a balance above zero, 0.000001. Six places, rounded up.
↳ cost_availablestringOn insufficient_balance: your account's balance, six places, rounded down.
↳ cost_missingstringOn insufficient_balance: cost_required less cost_available, the top-up that lets the call run.
↳ topup_urlstring (uri)Where to top up.