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"import RocketVerifier from "@rocketverifier/sdk";
const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);
const balance = await rv.getCredits();
console.log(balance.credits);import os
from rocketverifier import RocketVerifier
rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])
print(rv.get_credits().credits)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:
| Credential | Prefix | Use it for |
|---|---|---|
| Live API key | rv_live_ | Server-side calls on your own account. |
| Sandbox API key | rv_test_ | Tests and CI. Accepts only @sandbox.rocketverifier.com addresses and never charges. |
| Organization API key | rv_live_ | Calls billed to an organization, with its shared rate limit and IP allowlist. |
| OAuth access token | rv_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.
| Scope | Endpoints |
|---|---|
verify:single | POST /v1/verify, POST /v1/finder |
verify:bulk | POST /v1/verify/bulk, POST /v1/verify/bulk/upload, /preview, /confirm |
jobs:read | GET /v1/jobs and every GET /v1/jobs/{jobId} endpoint |
jobs:write | DELETE /v1/jobs/{jobId} |
monitors:read | GET /v1/monitors, GET /v1/monitors/{monitorId}, /runs |
monitors:write | POST, PATCH and DELETE on /v1/monitors, and /run |
webhooks:manage | Every /v1/webhooks endpoint except /events |
credits:read | GET /v1/credits |
account:read | GET /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 -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/bulkandPOST /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_unavailableinstead 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": {
"code": "insufficient_credits",
"message": "Need 1000 credits, have 640",
"details": { "required": 1000, "available": 640 }
}
}| Status | Typical codes | Meaning |
|---|---|---|
| 400 | no_emails, job_not_complete, invalid_domain | The request is well formed but cannot run. |
| 401 | unauthorized, api_key_expired, invalid_token | The credential is missing, wrong, revoked or expired. |
| 402 | insufficient_credits, api_key_spend_cap_reached | The balance or the key's monthly cap does not cover the charge. |
| 403 | insufficient_scope, insufficient_credits, sandbox_key_restricted, ip_not_allowed, account_suspended | The credential cannot make this call. A zero balance is refused here, before any work runs. |
| 404 | not_found | The resource does not exist or belongs to another account. |
| 409 | job_not_cancellable, job_not_awaiting_confirmation | The resource changed state. |
| 422 | validation_error | The body or a parameter failed validation. details.errors lists each problem. |
| 429 | rate_limited, daily_limit_reached | Slow down. Wait for Retry-After seconds. |
| 503 | maintenance, idempotency_unavailable, service_unavailable | Retry 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:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Unix time when the oldest request leaves the window. |
Retry-After | On 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.
| Endpoint | Default limit | Max limit |
|---|---|---|
GET /v1/jobs | 20 | 100 |
GET /v1/jobs/{jobId}/results | 100 | 1,000 |
GET /v1/webhooks/{webhookId}/logs | 50 | 100 |
GET /v1/monitors/{monitorId}/runs | 20 | 100 |
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.
/v1/statuscurl https://api.rocketverifier.com/v1/status{
"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
degradedwhen a core component is unhealthy, no node is healthy, or the engine is in maintenance.healthydegraded - versionstring
- uptime_secondsnumber
- timestampstring (date-time)
- componentsarray of objects
› Show 4 child fields
- nameenumdatabaseredisverification_nodesengineworker_queue
- statusenumhealthydegradedunhealthymaintenanceunknown
- latency_msnumber or null
Round trip time, for the database and Redis.
- detailsstring or null
Context such as
12/12 healthyfor the node fleet or the queue depth.
- sandbox_domainstring
- 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#
| Method | Path | What it does |
|---|---|---|
| POST | /v1/verify | Verify one address in real time. |
| POST | /v1/verify/bulk | Start a bulk job from a JSON list of up to 100,000 addresses. |
| POST | /v1/verify/bulk/upload | Start a bulk job from a CSV, TSV, TXT or XLSX file or a URL. |
| POST | /v1/verify/bulk/{jobId}/preview | Read the free list health preview of an upload. |
| POST | /v1/verify/bulk/{jobId}/confirm | Charge and start a previewed upload. |
| GET | /v1/jobs | List your bulk jobs. |
| GET | /v1/jobs/{jobId} | Get a job's status and counters. |
| GET | /v1/jobs/{jobId}/progress | Poll progress, throughput and ETA. |
| GET | /v1/jobs/{jobId}/results | Page through per-address results. |
| GET | /v1/jobs/{jobId}/download | Download every result as CSV or JSON. |
| DEL | /v1/jobs/{jobId} | Cancel a job and refund what was not processed. |
| POST | /v1/finder | Find an address from a name and a company domain. |
Automation#
| Method | Path | What it does |
|---|---|---|
| POST | /v1/monitors | Create a list health or domain authentication monitor. |
| GET | /v1/monitors | List 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}/run | Run a monitor now. |
| GET | /v1/monitors/{monitorId}/runs | Read a monitor's run history. |
| GET | /v1/webhooks/events | List the events you can subscribe to. |
| POST | /v1/webhooks | Register a webhook endpoint. |
| GET | /v1/webhooks | List 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}/test | Send a signed test event. |
| GET | /v1/webhooks/{webhookId}/logs | Read delivery attempts. |
| POST | /v1/webhooks/{webhookId}/rotate-secret | Issue a new signing secret. |
Tools and account#
| Method | Path | What it does |
|---|---|---|
| GET | /v1/tools/mx-lookup | MX records for a domain. |
| GET | /v1/tools/disposable-check | Is a domain or address disposable. |
| GET | /v1/tools/domain-auth | SPF, DKIM and DMARC with a score. |
| GET | /v1/tools/blacklist-monitor | DNS blacklist listings for a domain or IP. |
| POST | /v1/tools/verify-free | Free syntax, MX and disposable lookup. |
| GET | /v1/tools/activity/{email} | Your own verification history of an address. |
| GET | /v1/credits | Credit balance and usage. |
| GET | /v1/me | The account behind the credential. |
| GET | /v1/status | API 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