ReachReady
Back to overview
REST API v1 Reference

Developer API Documentation

Integrate real-time phone verification into your signup forms, CRM workflows, or outreach pipelines. Sub-200ms response times, 240+ countries.

Bearer Auth
Header: Authorization
Rate Limit
120 req/min per IP
Standard Billing
1 credit / verification
Batch Endpoint
Up to 1,000 / call

Core Architecture & Protocol Rules

1. Authentication

All requests require a secret API key passed as a Bearer token in the Authorization header. Keys start with pl_live_.

2. Safe Retries & Idempotency

Send a unique Idempotency-Key header on validation POSTs. Retrying network failures with the same key returns cached responses without charging extra credits.

3. Rate Limits & Headers

Rate limited to 120 requests/min per IP. Exceeding limits returns 429 Too Many Requests with standard reset headers.

API Endpoints

Base URL: https://api.reachready.io/v1

POST/v1/validate
Validate one number

Costs one standard credit and returns one complete validation object.

Request Parameters
numberstring (required)
countrystring ISO2 (optional)
cURL Code Example
curl -X POST "https://api.reachready.io/v1/validate" \
  -H "Authorization: Bearer pl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "number": "+919845012345",
    "country": "IN"
  }'
Sample 200 Response
{
  "status": "valid",
  "verdict": "sms_ok",
  "e164": "+919845012345",
  "line_type": "mobile",
  "carrier": "Airtel",
  "credits_charged": 1,
  "schema_version": "1.0"
}
POST/v1/validate/batch
Validate a batch

Accepts 1–1,000 numbers. Repeated numbers inside one request are charged once.

Request Parameters
numbersarray (1-1000 items)
cURL Code Example
curl -X POST "https://api.reachready.io/v1/validate" \
  -H "Authorization: Bearer pl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "number": "+919845012345",
    "country": "IN"
  }'
Sample 200 Response
{
  "results": [/* validation objects */],
  "credits_charged": 2,
  "count": 2
}
GET/v1/account
Read credit balance

Returns the current balance. This endpoint does not consume credits.

Request Parameters
No request body required. Read-only operation.
cURL Code Example
curl -X POST "https://api.reachready.io/v1/validate" \
  -H "Authorization: Bearer pl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "number": "+919845012345",
    "country": "IN"
  }'
Sample 200 Response
{
  "credits_balance": 10000,
  "credits_reserved": 0,
  "credits_available": 10000
}

Returned Data Schema (14 Fields)

Every successful check returns this structured payload.

status
Whether the input parses as a phone number.
reason
Why the number received its status or verdict.
e164
Normalized international number, or null.
national_format
Number formatted for its home country.
international_format
Human-readable international format.
country_name / country_iso2 / country_code
Resolved numbering-plan country.
location / timezone / utc_offset
Geography and current DST-aware offset.
line_type / carrier
Number category and numbering-plan carrier.
is_possible / is_valid
Length plausibility and range allocation.
verdict
Action: sms_ok, call_ok, review, or do_not_contact.
credits_charged / cached
Billing amount and whether metadata was already cached.
request_id / schema_version
Support trace and response contract version.

HTTP Error Codes

400

Invalid body, country code, tier, or batch larger than 1,000.

401

Missing, invalid, or revoked API key.

402

Not enough credits to complete the request.

429

Rate limit exceeded. Retry after the window resets.

500

Unexpected server failure. Retry with the same idempotency key.