This guide is the complete reference for the ApexVerify batch verification lifecycle. It covers every API call, every parameter, every response shape — and the exact order of operations from uploading a file to downloading your results.
Prerequisites: A valid API key (see Your First API Key) and a .txt file containing one email or phone number per line.
Base URL: https://api.apexverify.com
Authentication: All requests require the X-Api-Key: YOUR_API_KEY header.
The batch verification workflow has 7 steps. Each step maps to a specific API endpoint:
Endpoint: POST /v1/batch
Content-Type: multipart/form-data
Upload a .txt file with one email or phone number per line. The API creates a batch record and returns a batch_uuid that identifies this batch for all subsequent operations.
Save the batch_uuid. You will pass it to every subsequent request.
Save your batch_uuid — it is the key identifier for this batch in all subsequent calls.
Endpoint: PUT /v1/batch/{uuid}
Content-Type: application/json
Set the verification parameters for your batch. You can call this endpoint multiple times — parameters are updated each time. Only type and target_country are required.
Both caches are enabled by default and provide a 50% credit refund for cache-hit records:
The system always checks account cache first, then global cache.
max_account_cache_backoff and max_global_cache_backoff control the lookback window in days (1–180). A shorter window gives fresher results; a longer window maximizes cache hits and lowers cost.
Adjust and re-configure freely. You can call PUT as many times as you need — parameters are not locked until verification is launched. After changing parameters, always re-trigger parsing (Step 3) to recalculate cost and content summary.
Endpoint: PATCH /v1/batch/{uuid}
Request body: None
This triggers asynchronous content parsing. The server reads your uploaded file, validates each row, removes duplicates and malformed entries (per your configuration), and calculates the estimated verification cost.
Parsing has been triggered. The batch transitions to parsing_content status. Poll GET /v1/batch/{uuid} until it reaches ready_for_verification.
PATCH is idempotent and can be called multiple times. If you update parameters via PUT after an initial PATCH, simply call PATCH again to re-parse with the new configuration. There is no limit on re-parses before the batch is launched. Each re-parse recalculates the cost and content summary.
Typical iterate-and-refine flow:
Once parsing is complete (status = ready_for_verification), the found_content field in GET /v1/batch/{uuid}/details shows:
Credits are charged for valid_email count only.
Endpoint: GET /v1/batch/{uuid}/details
Returns detailed batch information, including status, parameters, parsing summary, verification cost, and (after completion) statistics. The response shape is discriminated by the status field.
Returned when status is parsing_content or internal_error:
If status is internal_error, an unexpected error occurred during parsing. Contact support at contact@apexverify.com and include your batch_uuid so the team can investigate.
Endpoint: POST /v1/batch/{uuid}
Request body: None
Starts the verification job. The batch must be in ready_for_verification status before calling this endpoint.
Verification has started. Proceed to Step 6 to poll for completion.
Insufficient credits? If your account doesn’t have enough credits to cover the net_email_cost or net_phone_cost, the API returns 402 Payment Required. Top up your credits from the Dashboard and retry.
Endpoint: GET /v1/batch/{uuid}
This lightweight status endpoint returns the batch’s current state. Poll it periodically until the status reaches verification_done.
Use exponential backoff when polling. Start with a 5-second interval and double it each cycle, capping at 60 seconds. This avoids unnecessary API calls and stays well within the 180 requests/minute rate limit. See API Rate Limits for details.
Endpoint: GET /v1/batch/{uuid}/export
Once verification_done, export your results. Two formats are available: structured JSON or a formatted XLSX spreadsheet.
Returns a JSON object keyed by the original email or phone value. Each key maps to a full result object.