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
/v1/assessAssess 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
| Field | Type | Description |
|---|---|---|
| phone | string | E.164 preferred; national format needs country. Up to 32 characters. Example +447700900123. |
| string | Any text: one that is not an address is scored (email_invalid), not refused. Up to 254 characters. Example jane@example.com. | |
| ip | string | IPv4 or IPv6 of the end user. Example 203.0.113.1. |
| country | string | ISO 3166-1 alpha-2 hint for national-format phones. Example GB. |
| reference | string | Your 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"
}geo_mismatch.Signals
/v1/phoneLook 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 whenstatusissuccess; 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_carrieris 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_carrierandline_statusare 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
| Field | Type | Description |
|---|---|---|
| phonerequired | string | E.164 preferred; national format needs country. Up to 32 characters. Example +447700900123. |
| country | string | ISO 3166-1 alpha-2 hint for national-format phones. Example GB. |
| level | string | How 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"
}
}
}+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./v1/emailVerify 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
| Field | Type | Description |
|---|---|---|
| emailrequired | string | Up to 254 characters. Example jane@example.com. |
| timeout | integer | The 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"
}
}
}deliverable./v1/ipLook 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
| Field | Type | Description |
|---|---|---|
| iprequired | string | IPv4 or IPv6. Example 203.0.113.66. |
Responses
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"
}
}
}routable: false, free.Files
/v1/filesYour 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"
}
]/v1/filesStart 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
| Field | Type | Description |
|---|---|---|
| namerequired | string | Up to 200 characters. Example leads.csv. |
| content_type | string | Example 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=…"
}/v1/files/{fileId}A file job and its progress
Parameters
| Field | Type | Description |
|---|---|---|
| fileIdrequired | string · path | Example 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"
]
]
}/v1/files/{fileId}Delete a file job and its objects
Parameters
| Field | Type | Description |
|---|---|---|
| fileIdrequired | string · path | Example fil_k2m9q7x3a8b4c5d6. |
Responses
curl -X DELETE https://api.prooftell.com/v1/files/fil_k2m9q7x3a8b4c5d6 \
-H "Authorization: Bearer pt_live_…"/v1/files/{fileId}/finishThe signed upload landed — analyse it
Parameters
| Field | Type | Description |
|---|---|---|
| fileIdrequired | string · path | Example 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"
]
]
}/v1/files/{fileId}/verifyRun 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
| Field | Type | Description |
|---|---|---|
| fileIdrequired | string · path | Example fil_k2m9q7x3a8b4c5d6. |
Request body
| Field | Type | Description |
|---|---|---|
| signalsrequired | array of string | What 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. |
| columns | FileColumns | |
| country | string | null | ISO 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"
}/v1/files/{fileId}/stopStop a running file
Parameters
| Field | Type | Description |
|---|---|---|
| fileIdrequired | string · path | Example fil_k2m9q7x3a8b4c5d6. |
Responses
curl -X POST https://api.prooftell.com/v1/files/fil_k2m9q7x3a8b4c5d6/stop \
-H "Authorization: Bearer pt_live_…"/v1/files/{fileId}/downloadA 15-minute link to the result
Parameters
| Field | Type | Description |
|---|---|---|
| fileIdrequired | string · path | Example fil_k2m9q7x3a8b4c5d6. |
| which | string · query | result: 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 (resultis a CSV in the upload's own delimiter; while running, a partial result with unreached rowspending, 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.
| Field | Type | Description |
|---|---|---|
| urlrequired | string (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=…"
}Account
/v1/pricingPublicThe 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
200The rate card. Body: Pricing.
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"
]
}/v1/balanceYour 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"
}
}
}
}Objects
PhoneRequest
| Field | Type | Description |
|---|---|---|
| phonerequired | string | E.164 preferred; national format needs country. Up to 32 characters. Example +447700900123. |
| country | string | ISO 3166-1 alpha-2 hint for national-format phones. Example GB. |
| level | string | How 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.
| Field | Type | Description |
|---|---|---|
| statusrequired | string | success: 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. |
| phone | string | The E.164 when the number is valid; as sent otherwise. |
| validrequired | boolean | |
| reason | string | Why 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_type | string | The 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_cost | string | What calling it costs, with line_type: short_code only. One of toll_free, standard_rate, premium_rate, unknown. |
| region | string | Where the number is registered, e.g. San Francisco, CA. |
| country | string | Example United Kingdom. |
| country_code | string | Example GB. |
| country_prefix | string | The calling code. Example 44. |
| international_format | string | Example +44 7700 900123. |
| national_format | string | Example 07700 900123. |
| e164 | string | Example +447700900123. |
| original_carrier | string | The carrier the number range was allocated to (the carrier today: current_carrier). |
| timezone | array of string | |
| geographical | boolean |
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:
| Field | Type | Description |
|---|---|---|
| levelrequired | string | The 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_carrier | 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). |
| line_status | 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. |
| fraud_score | FraudScoreResult | Fraud intelligence for the number, with the network facts (presence, portability, current carrier) that the lower levels show. |
| costrequired | string | What this call cost, in currency, six decimals: the line type's line plus the level’s line. Example 0.000000. |
| currencyrequired | string | One of USD. |
| signalsrequired | object | The 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. |
| ↳ basic | SignalLine | |
| ↳ line_type | SignalLine | |
| ↳ current_carrier | SignalLine | |
| ↳ line_status | SignalLine | |
| ↳ fraud_score | SignalLine |
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).
| Field | Type | Description |
|---|---|---|
| statusrequired | string | error with reason: invalid_number when the number could not be queried, free. One of success, error. |
| carrier | string | The current carrier. Example Orange Romania. |
| mcc | string | |
| mnc | string | |
| lrn | string | Local routing number (USA / Canada only). |
| ocn | string | Operating company number (USA / Canada only). |
| ported | boolean | |
| ported_date | string | Last known port, when the level carries it (fraud score). |
| original_carrier | object | The 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). |
| ↳ carrier | string | |
| ↳ mcc | string | |
| ↳ mnc | string | |
| ↳ ocn | string | |
| line_type | string | The 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_code | string | Example RO. |
| source | string | Present 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.
| Field | Type | Description |
|---|---|---|
| statusrequired | string | error with reason: invalid_number when the number could not be queried, free. One of success, error. |
| present | string | unknown when the network is not covered or did not say. One of yes, no, unknown. |
| reachable | boolean | null | present as a boolean; null when unknown. |
| reason | string | Why 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. |
| source | string | Present when the block was derived from the fraud score's answer. One of fraud_score. |
| covered | boolean | Whether 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. |
| ported | boolean | |
| network | string | The current network. |
| mcc | string | |
| mnc | string | |
| original_carrier | object | Instead of network, when the check could name only the network the number was issued to (covered: false; the call costs line type only). |
| ↳ carrier | string | |
| ↳ mcc | string | |
| ↳ mnc | string | |
| line_type | string | One of mobile, fixed_line. |
| country_code | string | Example GB. |
FraudScoreResult
Fraud intelligence for the number, with the network facts (presence, portability, current carrier) that the lower levels show.
| Field | Type | Description |
|---|---|---|
| statusrequired | string | error with reason invalid_number, invalid_number_length or invalid_number_range, free. One of success, error. |
| reason | string | On 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. |
| present | string | One of yes, no, unknown. |
| ported | boolean | |
| ported_date | string | |
| network | string | The current carrier. |
| mcc | string | |
| mnc | string | |
| score | integer | Propensity-for-fraud score: higher is riskier. 0 to 100. |
| risk_level | string | medium from 20, high from 50. One of low, medium, high. |
| service_type | string | The range’s service type: mobile, voip, premium_rate, satellite, machine_to_machine, freephone, geographic, msrn, … Example mobile. |
| service_type_code | integer | The numbering range's service type as a code, 1–33 (service_type names it). |
| line_type | string | One of mobile, fixed_line. |
| premium_rate | boolean | |
| voip | boolean | |
| iprn | boolean | Flagged as an international premium-rate number used to test access. |
| iprn_first_seen | string | |
| iprn_last_seen | string | |
| iprn_range | boolean | In a range flagged for premium-rate fraud (Wangiri, IRSF). |
| iprn_range_first_seen | string | |
| iprn_range_last_seen | string | |
| msrn | boolean | A mobile station roaming number advertised for roaming-call fraud. |
| msrn_first_seen | string | |
| msrn_last_seen | string | |
| original_network | string | |
| country_code | string | Example GB. |
EmailRequest
| Field | Type | Description |
|---|---|---|
| emailrequired | string | Up to 254 characters. Example jane@example.com. |
| timeout | integer | The 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).
| Field | Type | Description |
|---|---|---|
| statusrequired | string | unavailable only inside an assessment, when the signal did not run. One of success, error, unavailable. |
| string | As sent. | |
| resultrequired | string | The result label: deliverable, undeliverable, hardbounce, softbounce, catch_all, disposable, inbox_full, unknown, syntax_error. |
| deliverable | boolean | |
| did_you_mean | string | A likely correction of a misspelt domain, or empty. |
| user | string | The part before the @. |
| domain | string | |
| code | integer | The numeric result code. |
| verdictrequired | string | One of deliverable, undeliverable, risky, unknown. |
| reasonrequired | string | The verdict’s reason name, e.g. mailbox_exists, mailbox_rejected, disposable_domain, domain_catch_all, greylisted, mailbox_full, missing_at_sign. |
| billed | boolean | Whether this run counted: a run that did not is free. |
| suggested_action | string | The safe default for a sign-up form. One of accept, accept_and_confirm, reject. |
| flags | object | |
| ↳ disposable | boolean | |
| ↳ role_account | boolean | info@, sales@… |
| ↳ free_provider | boolean | |
| ↳ catch_all | boolean | |
| provider | string | The mail provider behind the domain, when known. |
| latency_ms | integer |
EmailResult
EmailVerification, plus the three ProofTell fields.
Every field of EmailVerification, and:
| Field | Type | Description |
|---|---|---|
| costrequired | string | Example 0.000000. |
| currencyrequired | string | One of USD. |
| signalsrequired | object | |
| SignalLine |
Pricing
| Field | Type | Description |
|---|---|---|
| versionrequired | string | |
| currencyrequired | string | One of USD. |
| servicesrequired | array of object | |
| curve | array of object | The 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_amounts | array of string | The amounts offered as buttons; any amount from min_topup is accepted. |
| min_topuprequired | string | Example 10.00. |
| subscription_amountsrequired | array of string |
PriceTier
| Field | Type | Description |
|---|---|---|
| uptorequired | integer | null | Checks of the signal this month, exclusive; null above the last boundary. |
| per_runrequired | string | Six decimals: exact at every step. Example 0.001750. |
| per_1000required | string | Example 1.75. |
Balance
| Field | Type | Description |
|---|---|---|
| currencyrequired | string | One of USD. |
| balancerequired | string | paid + promotional − held: the account's, shared by its organizations Example 124.0000. |
| paidrequired | string | |
| promotionalrequired | string | |
| heldrequired | string | Reserved by running files. |
| usage | object | This 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). |
| ↳ monthrequired | string | Example 2026-10. |
| ↳ runsrequired | integer | |
| ↳ amountrequired | string | Example 12.4000. |
| ↳ signalsrequired | object of object |
IpRequest
| Field | Type | Description |
|---|---|---|
| iprequired | string | IPv4 or IPv6. Example 203.0.113.66. |
IpIntelligence
The IP signal's own fields (also signals.ip.result of an assessment).
| Field | Type | Description |
|---|---|---|
| statusrequired | string | unavailable only inside an assessment, when the signal did not run. One of success, unavailable. |
| iprequired | string | |
| versionrequired | integer | One of 4, 6. |
| routablerequired | boolean | False 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_code | string | null | Example GB. |
| country | string | null | |
| region | string | null | |
| city | string | null | |
| latitude | number | |
| longitude | number | |
| accuracy_km | integer | |
| timezone | string | |
| asn | integer | null | Example 15169. |
| as_org | string | null | Example GOOGLE. |
| is_torrequired | boolean | |
| is_vpnrequired | boolean | |
| is_datacenterrequired | boolean | |
| is_anonymousrequired | boolean | Tor or VPN. |
| anycast | boolean | |
| data_version | string | Identifies the data set the answer came from. |
IpResult
IpIntelligence, plus the three ProofTell fields.
Every field of IpIntelligence, and:
| Field | Type | Description |
|---|---|---|
| costrequired | string | |
| currencyrequired | string | One of USD. |
| signalsrequired | object | |
| ↳ ip | SignalLine |
CreateFile
| Field | Type | Description |
|---|---|---|
| namerequired | string | Up to 200 characters. Example leads.csv. |
| content_type | string | Example text/csv. |
FileCreated
| Field | Type | Description |
|---|---|---|
| filerequired | FileJob | |
| upload_url | string (uri) | Signed flow only. |
| headers | object of string |
FileColumns
| Field | Type | Description |
|---|---|---|
| phonerequired | integer | 0-based column; -1 = none |
| emailrequired | integer | |
| iprequired | integer | |
| header_rowrequired | boolean |
VerifyFileRequest
| Field | Type | Description |
|---|---|---|
| signalsrequired | array of string | What 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. |
| columns | FileColumns | |
| country | string | null | ISO 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
| Field | Type | Description |
|---|---|---|
| idrequired | string | |
| namerequired | string | |
| statusrequired | string | One of uploading, ready, verifying, complete, failed, stopped, expired. |
| stage | string | |
| format | object | null | kind csv|tsv|txt|xlsx, delimiter, encoding, sheet |
| columns | FileColumns | null | |
| header | array of string | |
| samples | array of array of string | |
| rowsrequired | integer | |
| unique_rowsrequired | integer | |
| signalsrequired | array of string | |
| country | string | null | The default country the file runs with, for its national-format numbers; null for none. |
| holdrequired | string | Dollars held while running. |
| chargedrequired | string | |
| countersrequired | object of integer | rows, unique, duplicates, done, unavailable (rows a source could not judge), deferred (rows waiting for a source to answer again, retried later), <signal>_runs. |
| error | string | null | |
| created_atrequired | string (date-time) | |
| expires_atrequired | string (date-time) | Files and results are deleted 30 days after upload. |
SignalLine
| Field | Type | Description |
|---|---|---|
| statusrequired | string | One of ok, unavailable. |
| reason | string | On 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. |
| costrequired | string | Example 0.000000. |
AssessRequest
| Field | Type | Description |
|---|---|---|
| phone | string | E.164 preferred; national format needs country. Up to 32 characters. Example +447700900123. |
| string | Any text: one that is not an address is scored (email_invalid), not refused. Up to 254 characters. Example jane@example.com. | |
| ip | string | IPv4 or IPv6 of the end user. Example 203.0.113.1. |
| country | string | ISO 3166-1 alpha-2 hint for national-format phones. Example GB. |
| reference | string | Your own id for this check, echoed back. Up to 128 characters. |
Assessment
| Field | Type | Description |
|---|---|---|
| idrequired | string | Example asm_8f3k2m9q. |
| moderequired | string | test for sandbox calls made with a pt_test_ key. One of live, test. |
| reference | string | |
| scorerequired | integer | 0 = no risk found, 100 = highest risk. 0 to 100. |
| verdictrequired | string | Score 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. |
| reasonsrequired | array of Reason | |
| signalsrequired | object | One entry per supplied signal; result is that signal’s own fields, exactly as its standalone endpoint returns them. |
| ↳ phone | Signal | |
| ↳ result | 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. |
| Signal | ||
| ↳ result | EmailVerification | The email check's result: the email signal's own fields (also signals.email.result of an assessment, without billed). |
| ↳ ip | Signal | |
| ↳ result | IpIntelligence | The IP signal's own fields (also signals.ip.result of an assessment). |
| rulesetrequired | string | Version of the scoring rules that produced this result. Example 2026-10-07. |
| costrequired | string | The sum of the signal lines, six decimals. Example 0.007000. |
| currencyrequired | string | One of USD. |
| createdAtrequired | string (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.
| Field | Type | Description |
|---|---|---|
| coderequired | string | Stable: one of the codes above. Example email_disposable. |
| pointsrequired | integer | Example 35. |
| messagerequired | string | A readable sentence; it may change. Example The email address uses a disposable provider.. |
Signal
| Field | Type | Description |
|---|---|---|
| statusrequired | string | One of ok, unavailable. |
| reason | string | On unavailable, when known: not_offered — ProofTell does not offer the signal right now. |
| costrequired | string | Example 0.002500. |
| resultrequired | object | The signal's own fields (PhoneBaseResult, EmailVerification, IpIntelligence); on unavailable, just status: unavailable. |
Error
| Field | Type | Description |
|---|---|---|
| errorrequired | object | |
| ↳ coderequired | string | 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. |
| ↳ messagerequired | string | |
| ↳ retry_after | integer | Seconds to wait before retrying, on 429 and 503 (also the Retry-After header). |
| ↳ cost_required | string | On 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_available | string | On insufficient_balance: your account's balance, six places, rounded down. |
| ↳ cost_missing | string | On insufficient_balance: cost_required less cost_available, the top-up that lets the call run. |
| ↳ topup_url | string (uri) | Where to top up. |