Skip to content
RocketVerifierDOCS

Basics

API reference

In short

The RocketVerifier API is a JSON REST API at https://api.rocketverifier.com/v1. Authenticate every call with an API key or OAuth access token in the Authorization Bearer header, branch on the error code when a call fails, and read the X-RateLimit headers to pace your traffic.

On this page

Every RocketVerifier product, from the dashboard to the MCP server, runs on this API. It speaks JSON over HTTPS, uses one error shape everywhere and answers most single verifications in under half a second.

Base URL
api.rocketverifier.com/v1
Auth
Bearer API key or OAuth token
Format
JSON over HTTPS
Bulk
100,000 per job

Make your first request#

Send the key in the Authorization header and JSON in the body. This call checks your balance and costs nothing.

curl https://api.rocketverifier.com/v1/credits \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"

All paths in this reference start with /v1. Request bodies are application/json, except file uploads, which use multipart/form-data. Timestamps are ISO 8601 in UTC.

Authenticate requests#

Every endpoint that touches your account needs Authorization: Bearer <credential>. The credential is one of:

CredentialPrefixUse it for
Live API keyrv_live_Server-side calls on your own account.
Sandbox API keyrv_test_Tests and CI. Accepts only @sandbox.rocketverifier.com addresses and never charges.
Organization API keyrv_live_Calls billed to an organization, with its shared rate limit and IP allowlist.
OAuth access tokenrv_at_Apps acting for other RocketVerifier users through RocketVerifier Connect.

API keys carry scopes, and each endpoint checks one. A missing scope returns 403 insufficient_scope. Keys can also have an expiry date, an IP allowlist and a monthly spend cap. The authentication guide covers each, and OAuth scopes lists what apps can request.

ScopeEndpoints
verify:singlePOST /v1/verify, POST /v1/finder
verify:bulkPOST /v1/verify/bulk, POST /v1/verify/bulk/upload, /preview, /confirm
jobs:readGET /v1/jobs and every GET /v1/jobs/{jobId} endpoint
jobs:writeDELETE /v1/jobs/{jobId}
monitors:readGET /v1/monitors, GET /v1/monitors/{monitorId}, /runs
monitors:writePOST, PATCH and DELETE on /v1/monitors, and /run
webhooks:manageEvery /v1/webhooks endpoint except /events
credits:readGET /v1/credits
account:readGET /v1/me for OAuth tokens. API keys can always call it.

Choose a result version#

The RocketVerifier-Version header picks how catch-all addresses map onto status. With 2026-11-01, a catch-all address is risky. With 2025-01-01, it is unknown. Without the header, the key's own version applies, and keys created from November 2026 use 2026-11-01.

cURL
curl -X POST https://api.rocketverifier.com/v1/verify \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "RocketVerifier-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{"email": "maya@northwind.io"}'

The header applies to POST /v1/verify, job results and job downloads. Result versions explains when to move.

Retry safely with Idempotency-Key#

An Idempotency-Key header makes a write safe to retry: the same key within 24 hours returns the first response and never charges again. Use any unique string, such as a UUID.

  • Accepted on: POST /v1/verify, POST /v1/verify/bulk and POST /v1/verify/bulk/upload.
  • Scope: keys are stored per account, so two accounts never collide.
  • Store unavailable: a call with a key gets 503 idempotency_unavailable instead of running unprotected. Retry it, or drop the header.

The Node.js and Python SDKs send a fresh key on every write, so their automatic retries never double charge.

Handle errors#

Every error, on every endpoint, has the same shape. Branch on error.code, show error.message to people and read error.details for context.

Error body
{
  "error": {
    "code": "insufficient_credits",
    "message": "Need 1000 credits, have 640",
    "details": { "required": 1000, "available": 640 }
  }
}
StatusTypical codesMeaning
400no_emails, job_not_complete, invalid_domainThe request is well formed but cannot run.
401unauthorized, api_key_expired, invalid_tokenThe credential is missing, wrong, revoked or expired.
402insufficient_credits, api_key_spend_cap_reachedThe balance or the key's monthly cap does not cover the charge.
403insufficient_scope, insufficient_credits, sandbox_key_restricted, ip_not_allowed, account_suspendedThe credential cannot make this call. A zero balance is refused here, before any work runs.
404not_foundThe resource does not exist or belongs to another account.
409job_not_cancellable, job_not_awaiting_confirmationThe resource changed state.
422validation_errorThe body or a parameter failed validation. details.errors lists each problem.
429rate_limited, daily_limit_reachedSlow down. Wait for Retry-After seconds.
503maintenance, idempotency_unavailable, service_unavailableRetry after a short wait.

The errors reference lists every code with the fix.

Stay within rate limits#

Limits are counted per minute over a sliding window, per account (organization keys share one bucket per organization). Every response carries the current state:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetUnix time when the oldest request leaves the window.
Retry-AfterOn 429 only: seconds to wait.

Free and trial accounts get 30 requests per minute, pay as you go accounts 300, and subscriptions 600. Calls without a key get 5 per minute per IP address. A key can carry its own limit. Rate limits has the details and retry patterns.

Paginate lists#

List endpoints take page (starting at 1) and limit, and return total, page, limit and has_more. Request the next page while has_more is true.

EndpointDefault limitMax limit
GET /v1/jobs20100
GET /v1/jobs/{jobId}/results1001,000
GET /v1/webhooks/{webhookId}/logs50100
GET /v1/monitors/{monitorId}/runs20100

GET /v1/webhooks and GET /v1/monitors return the full list as an array. To export every result of a job in one response, use the download endpoint instead of paging.

Trace a request#

Every response carries an X-Request-ID header. Send your own (up to 128 characters) to follow a call through your logs, and include it when you contact support.

Check API status#

GET /v1/status returns the health of the API and its components. It needs no key.

GET/v1/status
cURL
curl https://api.rocketverifier.com/v1/status
Response 200
{
  "status": "healthy",
  "version": "1.1.0",
  "uptime_seconds": 86412.37,
  "timestamp": "2026-11-11T09:42:17.208114+00:00",
  "components": [
    { "name": "database", "status": "healthy", "latency_ms": 3.12, "details": null },
    { "name": "redis", "status": "healthy", "latency_ms": 0.84, "details": null },
    { "name": "verification_nodes", "status": "healthy", "latency_ms": null, "details": "12/12 healthy" },
    { "name": "engine", "status": "healthy", "latency_ms": null, "details": null },
    { "name": "worker_queue", "status": "healthy", "latency_ms": null, "details": "4 queued jobs" }
  ],
  "sandbox_domain": "sandbox.rocketverifier.com",
  "docs_url": "https://docs.rocketverifier.com"
}
  • statusenum

    degraded when a core component is unhealthy, no node is healthy, or the engine is in maintenance.

    healthydegraded
  • versionstring
  • timestampstring (date-time)
  • componentsarray of objects
    › Show 4 child fields
    • nameenum
      databaseredisverification_nodesengineworker_queue
    • statusenum
      healthydegradedunhealthymaintenanceunknown
    • latency_msnumber or null

      Round trip time, for the database and Redis.

    • detailsstring or null

      Context such as 12/12 healthy for the node fleet or the queue depth.

  • docs_urlstring

status is degraded when the database or Redis is unhealthy, when no verification node is healthy, or while the engine is in maintenance. An engine component with status maintenance explains what is paused in details.

Every endpoint#

Verification#

MethodPathWhat it does
POST/v1/verifyVerify one address in real time.
POST/v1/verify/bulkStart a bulk job from a JSON list of up to 100,000 addresses.
POST/v1/verify/bulk/uploadStart a bulk job from a CSV, TSV, TXT or XLSX file or a URL.
POST/v1/verify/bulk/{jobId}/previewRead the free list health preview of an upload.
POST/v1/verify/bulk/{jobId}/confirmCharge and start a previewed upload.
GET/v1/jobsList your bulk jobs.
GET/v1/jobs/{jobId}Get a job's status and counters.
GET/v1/jobs/{jobId}/progressPoll progress, throughput and ETA.
GET/v1/jobs/{jobId}/resultsPage through per-address results.
GET/v1/jobs/{jobId}/downloadDownload every result as CSV or JSON.
DEL/v1/jobs/{jobId}Cancel a job and refund what was not processed.
POST/v1/finderFind an address from a name and a company domain.

Automation#

MethodPathWhat it does
POST/v1/monitorsCreate a list health or domain authentication monitor.
GET/v1/monitorsList monitors.
GET/v1/monitors/{monitorId}Get a monitor and its latest result.
PATCH/v1/monitors/{monitorId}Update, pause or resume a monitor.
DEL/v1/monitors/{monitorId}Delete a monitor.
POST/v1/monitors/{monitorId}/runRun a monitor now.
GET/v1/monitors/{monitorId}/runsRead a monitor's run history.
GET/v1/webhooks/eventsList the events you can subscribe to.
POST/v1/webhooksRegister a webhook endpoint.
GET/v1/webhooksList webhook endpoints.
GET/v1/webhooks/{webhookId}Get one endpoint.
PATCH/v1/webhooks/{webhookId}Update, pause or resume an endpoint.
DEL/v1/webhooks/{webhookId}Delete an endpoint.
POST/v1/webhooks/{webhookId}/testSend a signed test event.
GET/v1/webhooks/{webhookId}/logsRead delivery attempts.
POST/v1/webhooks/{webhookId}/rotate-secretIssue a new signing secret.

Tools and account#

MethodPathWhat it does
GET/v1/tools/mx-lookupMX records for a domain.
GET/v1/tools/disposable-checkIs a domain or address disposable.
GET/v1/tools/domain-authSPF, DKIM and DMARC with a score.
GET/v1/tools/blacklist-monitorDNS blacklist listings for a domain or IP.
POST/v1/tools/verify-freeFree syntax, MX and disposable lookup.
GET/v1/tools/activity/{email}Your own verification history of an address.
GET/v1/creditsCredit balance and usage.
GET/v1/meThe account behind the credential.
GET/v1/statusAPI health.

Use an SDK#

The official SDKs wrap every endpoint above with typed results, retries on 429 and automatic idempotency keys.

Frequently asked questions

Is there a test mode?

Yes. Sandbox keys start with rv_test_ and return fixed results for @sandbox.rocketverifier.com addresses on every verification endpoint, without spending credits. Live keys start with rv_live_.

Can I send the API key in an X-API-Key header?

No. Every /v1 endpoint reads the key from Authorization Bearer only. Requests that send the key any other way get 401 unauthorized.

How do I avoid double charges when I retry?

Send an Idempotency-Key header on POST /v1/verify, POST /v1/verify/bulk and POST /v1/verify/bulk/upload. A retry with the same key within 24 hours returns the original response and charges nothing. The official SDKs add one to every write automatically.

Which endpoints work without an API key?

GET /v1/status, GET /v1/webhooks/events and the lookup tools under /v1/tools (except activity history). Calls without a key are limited to 5 per minute per IP address.

Updated 11 November 2026Suggest an edit