Asynchronous Verification API

Enterprise Verification API with Zero Provider Leakage

Integrate real-time and bulk contact verification into your application with a stable first-party REST contract. Built with asynchronous job queues, strict idempotency, HMAC-signed webhooks, and transparent micro-dollar ledger accounting.

Get API Key & Start Free Read API Reference Browse SDKs & Snippets

First-Party REST Contract Cryptographic Peppered Cache Zero Supplier Leak Idempotent Requests Integer Micro-USD Ledger

API Workbench

REST v1

curl -X POST https://api.phoneveriflo.com/api/v1/jobs \
  -H "Authorization: Bearer pv_live_sk_9481a7b8e19c" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "service": "phone-validation",
    "inputs": [
      "+14155552671",
      "+447700900123",
      "+33612345678"
    ],
    "webhook_url": "https://api.yourdomain.com/webhooks/phoneveriflo",
    "metadata": {
      "campaign_id": "cmp_2026_q3_onboarding",
      "user_segment": "enterprise_signups"
    }
  }'

201 Created Responseapplication/json

{
  "ok": true,
  "data": {
    "id": "job_94a821e0b5f1",
    "service": "phone-validation",
    "status": "queued",
    "item_count": 3,
    "max_quote_micros": 30000,
    "reserved_amount_micros": 30000,
    "quote_currency": "USD",
    "idempotency_key": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "created_at": "2026-08-14T04:30:00.000Z",
    "estimated_duration_ms": 450
  }
}

Interactive API Explorer

Complete Endpoints for Job Lifecycle & Webhooks

Test the exact request structures and normalized responses across the five core integration operations.

Create Verification Job

POST

Endpoint URI

POST /api/v1/jobs

Request Headers

AuthorizationBearer pv_live_••••••••••••••••

Content-Typeapplication/json

Idempotency-Key9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Strict Provider Isolation

Responses contain first-party normalized metadata only. Upstream vendor names, proxy nodes, and supplier tracking codes are strictly scrubbed server-side.

Implementation Snippet (curl)

curl -X POST https://api.phoneveriflo.com/api/v1/jobs \
  -H "Authorization: Bearer pv_live_sk_9481a7b8e19c" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "service": "phone-validation",
    "inputs": [
      "+14155552671",
      "+447700900123",
      "+33612345678"
    ],
    "webhook_url": "https://api.yourdomain.com/webhooks/phoneveriflo",
    "metadata": {
      "campaign_id": "cmp_2026_q3_onboarding",
      "user_segment": "enterprise_signups"
    }
  }'

Response Body Payload

{
  "ok": true,
  "data": {
    "id": "job_94a821e0b5f1",
    "service": "phone-validation",
    "status": "queued",
    "item_count": 3,
    "max_quote_micros": 30000,
    "reserved_amount_micros": 30000,
    "quote_currency": "USD",
    "idempotency_key": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "created_at": "2026-08-14T04:30:00.000Z",
    "estimated_duration_ms": 450
  }
}

Architecture & Reliability

Predictable 5-Stage Asynchronous Job Lifecycle

Bulk and enriched verification jobs are processed asynchronously through worker pipelines to avoid gateway timeouts and guarantee double-entry financial reconciliation.

1. queued

Ingestion & Ledger Lock

Job is registered under your own job ID. The maximum price quote in USD micros is frozen and atomically reserved in your wallet. Duplicates and invalid formats are detected deterministically.

2. preparing

Normalization & Peppered Cache

Inputs are standardized to E.164. The platform computes HMAC-SHA256(CACHE_PEPPER, scope/service/schema/input) to query the encrypted tenant cache without exposing plain text in memory indexes.

3. verifying

Provider-Isolated Execution

Cache misses are dispatched to the verified supplier adapter in private backend queues. Supplier identifiers and domain names are strictly quarantined behind our gateway boundary.

4. finalising

Canonicalization & Settlement

Supplier responses are sanitized and mapped into our canonical result schema. Double-entry ledger calculates actual billable charge; unused wallet reservations are unlocked instantly.

5. completed

Delivery & Signed Webhooks

Canonical result artifacts are encrypted and stored. Signed HMAC-SHA256 webhooks fire immediately to your endpoint with delivery retry policies up to 72 hours.

Stage 1: Ingestion & Ledger Lock

System State: status = "queued"

Automated & Auditable

Job is registered under your own job ID. The maximum price quote in USD micros is frozen and atomically reserved in your wallet. Duplicates and invalid formats are detected deterministically.

Ledger Invariant

Atomic reservation in integer USD micros before any worker thread spawns.

Cache Privacy

HMAC-SHA256 keyed with server secret; max 90-day contractual TTL cap.

Retry Safety

Idempotency keys prevent duplicate job creation across network drops.

Cost & Ledger Economics

Interactive Preflight Quote & Micro-Dollar Simulator

See how deduplication, invalid format pruning, and cache economics protect your wallet before any paid processing begins.

Simulate Your List Economics

Total Raw Contact Records50,000

1,000250,000500,000

Estimated Exact Duplicates12% (6,000 rows)

Tenant Cache Hit Ratio55% (23,375 cached)

No Charge for Formatting Errors or Exact Duplicates

Our deterministic preflight engine discards syntax errors (1,500 rows) and exact duplicates (6,000 rows) at zero cost.

Preflight Ledger Breakdown

Guaranteed Quote

Submitted Records50,000

Invalid Syntax (Pruned Free)1,500

Exact Duplicates (Deduplicated Free)6,000

Eligible Cache Hits ($0.004/rec)23,375

Fresh Verification Checks ($0.010/rec)19,125

Final Settled Charge

Frozen max was $425.00

$284.75

Total Customer Savings$140.25 (33.0% saved)

Security & Governance

Engineered for Production Resilience

Everything you need to run high-throughput verification pipelines securely.

HMAC Cache Pepper

Customer phone numbers and emails are never used as plain cache keys. Cache hashes are generated with HMAC-SHA256 using a cluster-level pepper and capped at a 90-day TTL.

Strict Idempotency

Pass an Idempotency-Key header with any write operation. If a network blip occurs during job submission, retrying with the same key returns the existing job without double-billing.

Zero Supplier Exposure

Third-party vendor domains, provider task IDs, upstream error messages, and raw backend endpoints are strictly stripped before reaching any customer API or webhook surface.

Signed Webhooks

Every webhook payload includes an X-Veriflo-Signature HMAC-SHA256 header. Supports 5-minute replay-attack tolerance checks and exponential retry policies over 72 hours.

Tiered Rate Limits

Default limits scale from 120 requests/min for standard keys up to 2,500 requests/min for enterprise tiers. Standard X-RateLimit-* and Retry-After headers included.

Encrypted Storage

All customer result artifacts, uploaded chunks, and export downloads are application-level encrypted at rest before object storage and served exclusively through authenticated presigned tokens.

API Reference

First-Party REST Endpoints

All endpoints require HTTPS and standard Bearer token authentication.

Core Verification Endpoints

Method	Endpoint	Purpose	Idempotent	Rate Limit
POST	`/api/v1/jobs`	Create asynchronous verification job	Yes (via header)	120 req/min
GET	`/api/v1/jobs/:id`	Poll job status, stage, counts, and charge	Yes	300 req/min
GET	`/api/v1/jobs/:id/results`	Download normalized result items with freshness	Yes	120 req/min
POST	`/api/v1/preflight`	Simulate duplicates, cache hits & max quote	Yes	120 req/min
GET	`/api/v1/services`	List enabled services, pricing, and schemas	Yes	300 req/min
POST	`/api/v1/jobs/:id/cancel`	Cancel queued or preparing job and unlock wallet	Yes	60 req/min

FAQ

Developer API Frequently Asked Questions

How does phoneveriflo prevent third-party provider leaks?

Our gateway acts as an absolute isolation barrier. All upstream supplier names, task IDs, proxy addresses, and provider error codes are completely stripped and mapped to our own standardized canonical models (e.g. valid/invalid, mobile/landline/voip, carrier name, country code).

Why are verification jobs asynchronous rather than synchronous?

Synchronous HTTP requests often time out during large batch operations or carrier network delays. Our asynchronous architecture lets you ingest thousands of records in sub-100ms, queue them safely, and receive signed webhooks as soon as the results are sealed.

How is money and billing handled during API execution?

All balances are tracked in integer USD micros ($1.00 USD = 1,000,000 micros). When a job is submitted, the maximum possible quote is frozen and atomically reserved. When processing completes, only the billable fresh and cached items are charged, and the remaining reservation is unlocked in the same database transaction.

What happens if my server misses a webhook event?

Our webhook dispatcher uses an exponential backoff retry schedule (retrying at 1m, 5m, 15m, 1h, 6h, 24h, up to 72 hours). You can also poll GET /api/v1/jobs/:id or query delivery attempts in your developer console.

Where can I find code examples in Python, Node, Go, or PHP?

Explore our dedicated Libraries & SDKs page for copy-ready, production-grade integration snippets across all popular backend languages.

Start Building Today

Ready to integrate verification into your application?

Create an API key in seconds, run preflight simulations for free, and pay only for verified results.

Create Free Account & Key View Language SDKs

Enterprise Verification API with Zero Provider Leakage

First-Party REST Contract Cryptographic Peppered Cache Zero Supplier Leak Idempotent Requests Integer Micro-USD Ledger

curl -X POST https://api.phoneveriflo.com/api/v1/jobs \ -H "Authorization: Bearer pv_live_sk_9481a7b8e19c" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \ -d '{ "service": "phone-validation", "inputs": [ "+14155552671", "+447700900123", "+33612345678" ], "webhook_url": "https://api.yourdomain.com/webhooks/phoneveriflo", "metadata": { "campaign_id": "cmp_2026_q3_onboarding", "user_segment": "enterprise_signups" } }'

{ "ok": true, "data": { "id": "job_94a821e0b5f1", "service": "phone-validation", "status": "queued", "item_count": 3, "max_quote_micros": 30000, "reserved_amount_micros": 30000, "quote_currency": "USD", "idempotency_key": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "created_at": "2026-08-14T04:30:00.000Z", "estimated_duration_ms": 450 } }

Method

Endpoint

Purpose

Idempotent

Rate Limit

POST

/api/v1/jobs

Create asynchronous verification job

Yes (via header)

120 req/min

GET

/api/v1/jobs/:id

Poll job status, stage, counts, and charge

Yes

300 req/min

GET

/api/v1/jobs/:id/results

Download normalized result items with freshness

Yes

120 req/min

POST

/api/v1/preflight

Simulate duplicates, cache hits & max quote

Yes

120 req/min

GET

/api/v1/services

List enabled services, pricing, and schemas

Yes

300 req/min

POST

/api/v1/jobs/:id/cancel

Cancel queued or preparing job and unlock wallet

Yes

60 req/min