API documentation

Verify numbers in real time or in bulk from your own systems. Authenticate every request with your token in the Authorization: Bearer <token> header. One credit is charged per verified number.

Base URL: https://truereach.one/v1

Single verification

POST/v1/verify

Body: {phone: "+14155552671"}. The phone is normalized (spaces and dashes stripped, leading + kept). Response includes the number, its status, and the check timestamp.

cURL

curl -X POST "https://truereach.one/v1/v1/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+14155552671"}'

Python

import requests

resp = requests.post(
    "https://truereach.one/v1/v1/verify",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={"phone": "+14155552671"},
)
print(resp.json())
# {"phone": "+14155552671", "status": "wa_registered", "checked_at": "..."}

Batch verification

POST/v1/verify/batch — multipart form upload of a .csv or .xlsx file (field file, up to 100,000 rows). The phone column is auto-detected from headers matching phone|mobile|number|tel|msisdn (case-insensitive), otherwise column 0 is used. Returns 202 {task_id, total, status}.

GET/v1/verify/tasks/{task_id} — poll until status is done. Task states: queued · processing · done · failed. Returns progress plus per-status summary counts.

GET/v1/verify/tasks/{task_id}/download — download the results as CSV: your original columns plus an appended verification_status column (409 if the task is not done).

cURL

curl -X POST "https://truereach.one/v1/v1/verify/batch" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@numbers.csv"

# -> {"task_id": "...", "total": 5000, "status": "queued"}

curl "https://truereach.one/v1/v1/verify/tasks/<task_id>" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl -O -J "https://truereach.one/v1/v1/verify/tasks/<task_id>/download" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Python

import requests, time

API = "https://truereach.one/v1"
H = {"Authorization": "Bearer YOUR_API_TOKEN"}

with open("numbers.csv", "rb") as f:
    task = requests.post(f"{API}/v1/verify/batch", headers=H,
                        files={"file": f}).json()

task_id = task["task_id"]
while True:
    t = requests.get(f"{API}/v1/verify/tasks/{task_id}", headers=H).json()
    print(t["processed"], "/", t["total"])
    if t["status"] == "done":
        break
    time.sleep(2)

csv_bytes = requests.get(f"{API}/v1/verify/tasks/{task_id}/download",
                         headers=H).content
open("numbers_verified.csv", "wb").write(csv_bytes)

Verification statuses

Status	Meaning
wa_registered	Number is registered on WhatsApp.
telegram_registered	Number is registered on Telegram.
dead	Dead or disconnected number.
inactive	Valid number but inactive on messaging apps.
unknown	Could not be determined.

Errors

Errors return {detail: "<code>"} with the matching HTTP status.

HTTP	Code	Meaning
401	not_authenticated	Missing or invalid Bearer token.
402	insufficient_credits	Balance is lower than the numbers requested.
409	email_taken	Email already registered.

All checks apply to numbers you submit as your own first-party customer data. Use for any other purpose violates the Terms of Service and may result in account suspension.