Skip to main content
POST
Python SDK

Credits and plans

PAYG is Pay-as-you-go. AYCE is All-you-can-eat. Email verification uses the same per-result prices on both plans. Uploading the file adds 0 credits. Verification is charged while the job is processed: one credit for each Valid or Invalid result. Metadata adds no cost.

When to use this endpoint

Use one upload for a large list instead of making a single-address call for every row. The batch runs asynchronously and returns a numeric process_id for the Utilities job endpoints.

Prepare your file

Supply a UTF-8 .csv or .json file with an email field. Keep your own reference column when you need to reconnect results to your records; output order can differ from input order.
emails.csv
Or use JSON records:
emails.json
The input records below come from the captured Contact Enrich example. Replace them with your own list. Verification results are returned by your batch; the input email addresses are not a promise of a Valid result.

Example

Set REVENUEBASE_API_KEY to your API key.

Read the response

Options, limits, and budget

  • Submit up to 300,000 input rows per file for a standard account. Larger files fail during processing.
  • Set metadata=true in the query string to include metadata in the output file. The default is false.
  • Budget one available credit per input row before starting. A job can fail with insufficient credits even though some eventual results would be free.
  • The final verification charge is Valid results + Invalid results. Metadata has no surcharge.
  • Repeated submissions create new jobs and can charge again for the same addresses.
The real-time endpoint’s 1-per-second limit describes individual checks; one batch upload processes the entire submitted list.

Poll, then download

Upload a batch, check its status, then download the results. Poll every 5 to 10 seconds, slowing down for longer jobs. Stop on COMPLETED, CANCELLED, or ERROR. A cancelled job may have partial output; a job cancelled before processing may have none. Output includes the original fields and each address’s status. Metadata adds the fields described in statuses and metadata. CSV normalizes failed individual checks to Unknown; JSON output can contain Error for those rows. Both are inconclusive and add no verification charge.

Errors and retries

An unsupported filename extension returns 400. A malformed file, missing email column, excessive row count, or insufficient budget can appear as an ERROR job after an accepted upload. Read the job message before submitting a corrected file. If an upload response is lost, list your jobs before uploading again to avoid creating a second paid run.

Next steps

Get batch job status using the returned process_id.

Authorizations

x-key
string
header
required

Query Parameters

metadata
boolean
default:false

Include verification metadata at no extra credit cost. False by default; set true for provider, MX, gateway, and reason details. Metadata is included at no extra cost.

Body

multipart/form-data
requested_file
file
required

Response

Successful Response

process_id
integer
required
filename
string
required
status
string
required