Create and inspect asynchronous verification jobs.
The phoneveriflo Jobs API allows you to submit up to 100,000 records per job, track progress through provider-neutral states, and manage batch execution with full ledger transparency.
curl -X POST https://api.phoneveriflo.com/api/v1/jobs \
-H "Authorization: Bearer pv_live_your_key" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"service": "phone-validation",
"inputs": [
"+14155552671",
"+14155552672",
"+447700900123"
],
"countryCode": "US",
"forceFresh": false
}'All requests require Bearer authorization with high-entropy secret tokens.
Bearer pv_live_...→Prevent duplicate jobs and safe automatic retries using 24h unique keys.
Idempotency-Key: uuid→Predictable Token Bucket model at 100 req/s with standard Retry-After headers.
100 req/s burst→Strict date-based compatibility guarantees with 12-month deprecation windows.
v1 (2026-08-11)→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.
Configure request parameters and click Send Request to preview live execution.
The Asynchronous Job State Machine
Lifecycle StatesAll jobs transition through strict, predictable, provider-neutral states.
phoneveriflo enforces a unified lifecycle across all 35+ verification services. You will never encounter vendor-specific status codes or unmapped states.
| State | Description | Action Required / Next State |
|---|---|---|
| queued | Job accepted, preflight quote calculated and balance reserved. | Waiting for worker pickup. Next: preparing |
| preparing | Normalizing inputs, chunking large batches, resolving HMAC cache hits. | Automatic worker execution. Next: verifying |
| verifying | Fresh checks actively executing across live networks. | Automatic worker execution. Next: finalising |
| finalising | Encrypting final result artifacts, reconciling ledger charges. | Releasing unused quote reservation. Next: completed |
| completed | All records processed successfully and results ready. | Ready for download via GET /api/v1/jobs/{id}/results |
| partial | Completed with some row-level network timeouts or invalid formats. | Results available with row-level error tags |
| failed | Unrecoverable error (e.g. wallet depletion, corrupt input). | Terminal state; full quote reservation refunded |
Common Integration Questions
Can I cancel an active job?
You can cancel a job while it is in the "queued" or "preparing" state. Once verification chunks are dispatched to live networks ("verifying"), the job runs to completion and any unverified items are refunded.
Related Guides & API References
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.