Run your first verification in under 5 minutes.
Follow this step-by-step guide to obtain your API key, submit a verification job, track asynchronous progress, and download normalized results.
# Check your workspace wallet and API connectivity
curl https://api.phoneveriflo.com/api/v1/jobs \
-H "Authorization: Bearer pv_live_your_key"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.
Step 1: Obtain Your Workspace API Key
PrerequisiteGenerate a high-entropy secret token with the required permissions.
1. Sign in to your phoneveriflo workspace at Customer Dashboard (/app).
2. Navigate to Developer Center -> API Keys (/app/developers).
3. Click Generate New API Key, select scopes (jobs:write, jobs:read), and assign an optional label (e.g. production-backend-svc).
4. Copy the secret key immediately. It starts with pv_live_ (or pv_test_) and will never be shown again.
5. Store the key in your secure server environment variables as PHONEVERIFLO_API_KEY. Never include this key in client-side code, mobile apps, or public Git repos.
Step 2: Prepare Your Input Data
FormattingUnderstand input formatting rules to minimize preflight rejections.
The phoneveriflo API accepts an array of strings in the inputs body parameter:
- Phone Numbers: Recommended in international E.164 format (e.g. +14155552671, +447700900123). If country code is omitted, provide countryCode: "US" in the request body.
- Email Addresses: RFC 5322 compliant email strings (e.g. [email protected]).
- Batch Limits: Each request accepts between 1 and 100,000 items. Preflight automatically identifies duplicate rows and invalid syntax before processing.
Step 3: Submit Verification Request
POST /api/v1/jobsSend an asynchronous job creation request.
Submit a POST request to https://api.phoneveriflo.com/api/v1/jobs.
Always supply an Idempotency-Key header with a unique UUID v4. If your network connection drops and your client retries the request, phoneveriflo will return the existing job without double-charging.
Step 4: Track Progress & Handle Status Transitions
LifecycleFollow the asynchronous state machine or configure instant webhooks.
The API responds immediately with HTTP 202 Accepted and the initial job state.
Possible job states include: queued, preparing, verifying, finalising, completed, partial, failed.
Recommended Polling Strategy: Poll GET /api/v1/jobs/{id} every 1–2 seconds for small jobs, or every 5–10 seconds for large jobs (>10,000 rows). In production, configure Webhooks (/docs/webhooks) for instant zero-polling event push.
Step 5: Download Normalized Output
GET /resultsRetrieve clean canonical verification outputs with freshness metadata.
When the job status reaches completed or partial, call GET /api/v1/jobs/{id}/results.
Results are streamed as standard UTF-8 CSV with explicit column headers: input, normalized, valid, line_type, carrier, country, freshness, checked_at.
Common Integration Questions
Do I get charged for duplicate phone numbers in my batch?
No. Preflight detects exact duplicates within your submission and excludes them from live paid checks. You receive normalized results for all rows while only paying for unique verifications.
What is the maximum allowed batch size per job?
You can submit up to 100,000 items in a single POST /api/v1/jobs request. For larger lists (e.g. 1M+ records), divide into 100K batches or use the bulk file upload UI.
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.