API-FIRST VERIFICATIONVerified API v1Updated: August 12, 2026

Build verification into your product in minutes.

A developer-first REST platform for high-throughput phone, email, and channel reachability verification with transparent preflight quotes, frozen pricing, and provider-neutral freshness metadata.

Get your API key Open API Sandbox OpenAPI 3.1 Spec

HTTPS / Bearer Auth

curl -X POST https://api.phoneveriflo.com/api/v1/jobs \
  -H "Authorization: Bearer pv_live_9f82c418ab402e..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "phone-validation",
    "inputs": [
      "+14155552671",
      "+447700900123",
      "+61491570156"
    ],
    "countryCode": "US",
    "forceFresh": false
  }'

Authentication

All requests require Bearer authorization with high-entropy secret tokens.

Bearer pv_live_...→

Idempotency

Prevent duplicate jobs and safe automatic retries using 24h unique keys.

Idempotency-Key: uuid→

Rate Limits

Predictable Token Bucket model at 100 req/s with standard Retry-After headers.

100 req/s burst→

Stable Versioning

Strict date-based compatibility guarantees with 12-month deprecation windows.

v1 (2026-08-11)→

Interactive Sandbox

Test API Requests in Real Time

Build and simulate verification requests directly in your browser. Generates live code snippets and previews the exact response schema.

Sandbox Mode

HTTP Method & Endpoint

Verification Service

Default Country Code

Input Records (1 to 100,000)3 rows

forceFresh (Bypass Cache)

Simulated Response

Configure request parameters and click Send Request to preview live execution.

The Verification Request Lifecycle

Core Workflow

Understand the end-to-end job execution model from synchronous preflight to asynchronous verified output.

Every verification in phoneveriflo follows a transparent 5-stage lifecycle designed for high throughput, predictable ledger accounting, and absolute privacy.

1. **Preflight Normalization**: Your input records (up to 100,000 per request) are sanitized into canonical E.164 phone formats or RFC 5322 emails. Exact duplicates and unparseable rows are identified.

2. **HMAC Cache Lookup & Quote Freeze**: Privacy-preserving HMAC-SHA256 tokens check for unexpired verified records in your organization cache. A guaranteed maximum price quote is calculated in integer USD micros.

3. **Atomic Wallet Reservation**: The exact quoted maximum amount is reserved in your ledger balance before any external check runs.

4. **Asynchronous Verification Engine**: The job is queued into the background worker pool. Eligible cache hits are resolved in milliseconds, while fresh checks execute over high-speed networks.

5. **Canonical Result & Final Ledger Settlement**: Results are encrypted at rest with AES-256 and made downloadable via CSV or JSON. Unused reservation amounts (e.g. from duplicates or cache hits) are atomically released back to your balance.

1. AuthenticateBearer Auth

Pass high-entropy API key with scoped permissions in the Authorization header.

2. Create JobPOST /jobs

Submit up to 100K inputs. Receive immediate 202 Accepted with preflight breakdown.

3. Preflight & CacheZero Waste

Deduplicate, validate formats, and resolve HMAC encrypted cache hits.

4. Stream WebhooksEvent Driven

Receive signed HMAC-SHA256 event notifications when verification completes.

Platform Architectural Invariants

Guarantees

Non-negotiable architectural principles that protect your brand and wallet.

**Zero Provider Leaks**: phoneveriflo is a strict white-label platform. The API contract, response schemas, error envelopes, and webhook events NEVER reveal upstream vendor names, task IDs, raw payloads, or third-party hostnames.

**Micro-USD Double-Entry Accounting**: All pricing and wallet balances are stored in integer USD micros ($1.00 USD = 1,000,000 micros). There is zero floating-point imprecision or surprise overcharging.

**Configurable Freshness & 90-Day Cap**: Every returned record includes verified checked_at and expires_at ISO 8601 timestamps. Stale records older than your policy (or the hard 90-day privacy cap) are automatically re-verified.

**Encrypted at Rest**: Raw inputs, intermediate chunks, and final result artifacts are AES-256 application-layer encrypted in secure object storage.

Concept	Specification	Benefit to Developer
Input Batch Size	1 to 100,000 records per job	Handle single lookups and massive bulk lists with identical API contracts
Accounting Precision	Integer USD Micros (1 USD = 1M micros)	Exact double-entry reconciliation; zero floating-point rounding discrepancies
Cache Keys	HMAC-SHA256(Secret, Scope + Input)	Zero PII exposed in cache stores; instant reuse across repetitive workflows
Idempotency Window	24 Hours with state replay	Safe automatic client retries without double charging or duplicate jobs
Webhooks	HMAC-SHA256 with timestamp headers	Zero polling required; immune to replay attacks and network drops

API Endpoints Quick Reference

REST v1

Base URL: https://api.phoneveriflo.com/api/v1

All endpoints require HTTPS and valid Bearer authentication. All successful create requests return HTTP 202 Accepted.

POST/api/v1/jobs

Create and immediately approve verification job

Submits an array of phone numbers or email addresses for asynchronous verification. Performs preflight quote calculation, reserves balance, and enqueues the job.

Headers

Authorizationrequired

stringBearer pv_live_...

Idempotency-Key

stringUnique UUID v4 to prevent duplicate submissions on retry

Content-Typerequired

stringapplication/json

Request Body

servicerequired

stringService slug (e.g. phone-validation, whatsapp, telegram, carrier-single)

inputsrequired

string[]Array of 1 to 100,000 phone numbers or email addresses

countryCode

stringDefault ISO 2-letter country code fallback for unformatted numbers

forceFresh

booleanBypass cache and force fresh live network verification

Request Example

curl -X POST https://api.phoneveriflo.com/api/v1/jobs \
  -H "Authorization: Bearer pv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"phone-validation","inputs":["+14155552671"]}'

Response (202)JSON

{
  "id": "job_01j73a6e2jq9bk8ze7yv2vmR",
  "status": "queued",
  "preflight": {
    "totalRows": 1,
    "invalidRows": 0,
    "duplicateRows": 0,
    "cacheHits": 0,
    "freshChecks": 1,
    "maxQuoteMicros": 10000,
    "quoteId": "quot_9f81a7b4"
  }
}

GET/api/v1/jobs/{id}

Get job status and progress

Retrieves real-time processing status, row counts, cache hit metrics, and completion timestamps.

Request Example

curl https://api.phoneveriflo.com/api/v1/jobs/job_01j73a6e2jq9bk8ze7yv2vmR \
  -H "Authorization: Bearer pv_live_your_key"

Response (200)JSON

{
  "id": "job_01j73a6e2jq9bk8ze7yv2vmR",
  "status": "completed",
  "totalRows": 1,
  "cacheHits": 0,
  "freshRecords": 1,
  "successRecords": 1,
  "failedRecords": 0,
  "createdAt": "2026-08-12T14:32:00.000Z",
  "updatedAt": "2026-08-12T14:32:04.000Z",
  "resultUrl": "/api/v1/jobs/job_01j73a6e2jq9bk8ze7yv2vmR/results"
}

GET/api/v1/jobs/{id}/results

Download canonical CSV / JSON results

Fetches decrypted canonical verification results containing normalized fields, validity states, and freshness metadata.

Request Example

curl https://api.phoneveriflo.com/api/v1/jobs/job_01j73a6e2jq9bk8ze7yv2vmR/results \
  -H "Authorization: Bearer pv_live_your_key" \
  -o results.csv

Response (200)JSON

input,normalized,valid,line_type,carrier,country,freshness,checked_at
+14155552671,+14155552671,true,mobile,Verizon,US,fresh,2026-08-12T14:32:03Z

Frequently Asked Questions

Common Integration Questions

Where do I get my API key?

Log in to your phoneveriflo Customer Workspace, navigate to Developer Center (/app/developers), and click "Create API Key". Choose your required scopes (jobs:write, jobs:read). The full key is displayed only once upon generation.

How fast does asynchronous verification complete?

Cached records resolve within 15–50 milliseconds. Fresh network checks process concurrently across distributed worker pools, typically finishing 100 rows in under 2 seconds and 50,000 rows in 30–60 seconds.

Can I test without spending wallet balance?

You can test input validation and preflight calculations. Invalid format rows and exact duplicate records are always pre-filtered free of charge. For live checks, use small batch tests of 1–5 records.

What happens if my server loses connection during a job?

Because jobs run asynchronously, network interruptions do not affect execution. You can safely poll GET /api/v1/jobs/{id} or rely on our HMAC-signed webhook delivery to receive the results.

Related Guides & API References

Start Building

Ready to build with phoneveriflo?

Generate your secret API key in 30 seconds. Test preflight quotes and receive provider-neutral results with full freshness auditability.

Get your API key → View pricing

API-FIRST VERIFICATIONVerified API v1Updated: August 12, 2026

Build verification into your product in minutes.

A developer-first REST platform for high-throughput phone, email, and channel reachability verification with transparent preflight quotes, frozen pricing, and provider-neutral freshness metadata.

Get your API key Open API Sandbox OpenAPI 3.1 Spec

HTTPS / Bearer Auth

curl -X POST https://api.phoneveriflo.com/api/v1/jobs \
  -H "Authorization: Bearer pv_live_9f82c418ab402e..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "phone-validation",
    "inputs": [
      "+14155552671",
      "+447700900123",
      "+61491570156"
    ],
    "countryCode": "US",
    "forceFresh": false
  }'

Authentication

All requests require Bearer authorization with high-entropy secret tokens.

Bearer pv_live_...→

Idempotency

Prevent duplicate jobs and safe automatic retries using 24h unique keys.

Idempotency-Key: uuid→

Rate Limits

Predictable Token Bucket model at 100 req/s with standard Retry-After headers.

100 req/s burst→

Stable Versioning

Strict date-based compatibility guarantees with 12-month deprecation windows.

v1 (2026-08-11)→

Interactive Sandbox

Test API Requests in Real Time

Build and simulate verification requests directly in your browser. Generates live code snippets and previews the exact response schema.

Sandbox Mode

HTTP Method & Endpoint

Verification Service

Default Country Code

Input Records (1 to 100,000)3 rows

forceFresh (Bypass Cache)

Simulated Response

Configure request parameters and click Send Request to preview live execution.

The Verification Request Lifecycle

Core Workflow

Understand the end-to-end job execution model from synchronous preflight to asynchronous verified output.

Every verification in phoneveriflo follows a transparent 5-stage lifecycle designed for high throughput, predictable ledger accounting, and absolute privacy.

3. **Atomic Wallet Reservation**: The exact quoted maximum amount is reserved in your ledger balance before any external check runs.

4. **Asynchronous Verification Engine**: The job is queued into the background worker pool. Eligible cache hits are resolved in milliseconds, while fresh checks execute over high-speed networks.

1. AuthenticateBearer Auth

Pass high-entropy API key with scoped permissions in the Authorization header.

2. Create JobPOST /jobs

Submit up to 100K inputs. Receive immediate 202 Accepted with preflight breakdown.

3. Preflight & CacheZero Waste

Deduplicate, validate formats, and resolve HMAC encrypted cache hits.

4. Stream WebhooksEvent Driven

Receive signed HMAC-SHA256 event notifications when verification completes.

Platform Architectural Invariants

Guarantees

Non-negotiable architectural principles that protect your brand and wallet.

**Encrypted at Rest**: Raw inputs, intermediate chunks, and final result artifacts are AES-256 application-layer encrypted in secure object storage.

Concept	Specification	Benefit to Developer
Input Batch Size	1 to 100,000 records per job	Handle single lookups and massive bulk lists with identical API contracts
Accounting Precision	Integer USD Micros (1 USD = 1M micros)	Exact double-entry reconciliation; zero floating-point rounding discrepancies
Cache Keys	HMAC-SHA256(Secret, Scope + Input)	Zero PII exposed in cache stores; instant reuse across repetitive workflows
Idempotency Window	24 Hours with state replay	Safe automatic client retries without double charging or duplicate jobs
Webhooks	HMAC-SHA256 with timestamp headers	Zero polling required; immune to replay attacks and network drops

API Endpoints Quick Reference

REST v1

Base URL: https://api.phoneveriflo.com/api/v1

All endpoints require HTTPS and valid Bearer authentication. All successful create requests return HTTP 202 Accepted.

POST/api/v1/jobs

Create and immediately approve verification job

Submits an array of phone numbers or email addresses for asynchronous verification. Performs preflight quote calculation, reserves balance, and enqueues the job.

Headers

Authorizationrequired

stringBearer pv_live_...

Idempotency-Key

stringUnique UUID v4 to prevent duplicate submissions on retry

Content-Typerequired

stringapplication/json

Request Body

servicerequired

stringService slug (e.g. phone-validation, whatsapp, telegram, carrier-single)

inputsrequired

string[]Array of 1 to 100,000 phone numbers or email addresses

countryCode

stringDefault ISO 2-letter country code fallback for unformatted numbers

forceFresh

booleanBypass cache and force fresh live network verification

Request Example

curl -X POST https://api.phoneveriflo.com/api/v1/jobs \
  -H "Authorization: Bearer pv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"phone-validation","inputs":["+14155552671"]}'

Response (202)JSON

{
  "id": "job_01j73a6e2jq9bk8ze7yv2vmR",
  "status": "queued",
  "preflight": {
    "totalRows": 1,
    "invalidRows": 0,
    "duplicateRows": 0,
    "cacheHits": 0,
    "freshChecks": 1,
    "maxQuoteMicros": 10000,
    "quoteId": "quot_9f81a7b4"
  }
}

GET/api/v1/jobs/{id}

Get job status and progress

Retrieves real-time processing status, row counts, cache hit metrics, and completion timestamps.

Request Example

curl https://api.phoneveriflo.com/api/v1/jobs/job_01j73a6e2jq9bk8ze7yv2vmR \
  -H "Authorization: Bearer pv_live_your_key"

Response (200)JSON

{
  "id": "job_01j73a6e2jq9bk8ze7yv2vmR",
  "status": "completed",
  "totalRows": 1,
  "cacheHits": 0,
  "freshRecords": 1,
  "successRecords": 1,
  "failedRecords": 0,
  "createdAt": "2026-08-12T14:32:00.000Z",
  "updatedAt": "2026-08-12T14:32:04.000Z",
  "resultUrl": "/api/v1/jobs/job_01j73a6e2jq9bk8ze7yv2vmR/results"
}

GET/api/v1/jobs/{id}/results

Download canonical CSV / JSON results

Fetches decrypted canonical verification results containing normalized fields, validity states, and freshness metadata.

Request Example

curl https://api.phoneveriflo.com/api/v1/jobs/job_01j73a6e2jq9bk8ze7yv2vmR/results \
  -H "Authorization: Bearer pv_live_your_key" \
  -o results.csv

Response (200)JSON

input,normalized,valid,line_type,carrier,country,freshness,checked_at
+14155552671,+14155552671,true,mobile,Verizon,US,fresh,2026-08-12T14:32:03Z

Frequently Asked Questions

Common Integration Questions

Where do I get my API key?

How fast does asynchronous verification complete?

Can I test without spending wallet balance?

What happens if my server loses connection during a job?

Because jobs run asynchronously, network interruptions do not affect execution. You can safely poll GET /api/v1/jobs/{id} or rely on our HMAC-signed webhook delivery to receive the results.

Related Guides & API References

Start Building

Ready to build with phoneveriflo?

Generate your secret API key in 30 seconds. Test preflight quotes and receive provider-neutral results with full freshness auditability.

Get your API key → View pricing