{ "openapi": "3.0.1", "info": { "title": "Prime Verifier API", "description": "High-accuracy email verification and email finding. Checks syntax, DNS/MX, disposable and role addresses, free providers, and real SMTP mailbox existence, then returns a clear verdict plus a graded risk score.\n\n**Base URL:** `https://api.primeverifier.com`\n\n**Authentication:** send your API key in the `X-API-KEY` header. Create keys in your dashboard under Profile, API Keys.\n\n**Billing:** you are charged only for a decisive result. `unknown` and `error` are free.\n\n**Responses:** every call returns `{ status, data, error }`. Errors carry a stable numeric `error.code`.", "termsOfService": "https://primeverifier.com/terms", "contact": { "name": "Prime Verifier Support", "url": "https://developers.primeverifier.com", "email": "support@primeverifier.com" }, "version": "v1" }, "servers": [ { "url": "https://api.primeverifier.com", "description": "Production" } ], "paths": { "/v1/jobs": { "post": { "tags": [ "Bulk" ], "summary": "Upload a CSV file to start a bulk verification job.\r\nKeeps the user's ORIGINAL file (all columns) and verifies the chosen email column. The result columns\r\nare merged back into the original file at download time. `emailColumn` is the zero-based index of\r\nthe email column; `dedupe` controls whether the downloaded file keeps one row per address.\r\nMaximum file size: 50 MB. Maximum unique emails: 500,000.", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "emailColumn": { "type": "integer", "format": "int32" }, "dedupe": { "type": "boolean" } } }, "encoding": { "file": { "style": "form" }, "emailColumn": { "style": "form" }, "dedupe": { "style": "form" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } }, "get": { "tags": [ "Bulk" ], "summary": "List all bulk jobs for the authenticated user (paginated).", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/jobs/{id}": { "get": { "tags": [ "Bulk" ], "summary": "Get details for a single bulk job.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } }, "delete": { "tags": [ "Bulk" ], "summary": "Cancel a pending or processing bulk job.\r\nCannot cancel jobs that are already completed or cancelled.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/jobs/{id}/download": { "get": { "tags": [ "Bulk" ], "summary": "Download the CSV results for a bulk job. When the job is `Completed` this is the full file;\r\nwhen it is still `Processing` it streams the rows verified so far (a partial download, flagged\r\nwith the `X-Partial-Result` response header) so callers don't wait for a huge job to finish.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "columns", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/jobs/{id}/stream": { "get": { "tags": [ "Bulk" ], "summary": " Live progress stream (Server-Sent Events). Emits a `progress` event about once a second with\r\n the job's current status + counts, then a final `done` event when it reaches a terminal state\r\n, so a client sees near-real-time progress over a single connection instead of polling.", "description": "Per-email result push (each verdict the instant it lands) is the next layer and needs a shared bus\r\n(Redis pub/sub) between the Worker and API; this DB-backed progress stream needs no extra infra.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/credits/balance": { "get": { "tags": [ "Credit" ], "summary": "Get current credit balance for the authenticated user.\r\nBalance is cached in Redis for 30 seconds.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/credits/transactions": { "get": { "tags": [ "Credit" ], "summary": "Get paginated credit transaction history.\r\nOptionally filter by transaction type (`Added`, `Used`, `Adjusted`).", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 20 } }, { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/CreditTransactionType" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/credits/packages": { "get": { "tags": [ "Credit" ], "summary": "List all active credit packages and current promotions. No API key required.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/credits/orders": { "get": { "tags": [ "Credit" ], "summary": "Get paginated order history for the authenticated user.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPagedResultApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/finder": { "post": { "tags": [ "Finder" ], "summary": "Find one email. POST /v1/finder/single (or /v1/finder).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FinderRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FinderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderResponseApiResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/finder/single": { "post": { "tags": [ "Finder" ], "summary": "Find one email. POST /v1/finder/single (or /v1/finder).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FinderRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FinderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderResponseApiResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/finder/batch": { "post": { "tags": [ "Finder" ], "summary": "Find many emails in ONE request (tenant integration). POST /v1/finder/batch\r\n Body: { \"contacts\": [ { \"first_name\", \"last_name\", \"domain\" }, … ] } (max 100). Synchronous, like /v1/verify/batch.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderBatchRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FinderBatchRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FinderBatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/finder/jobs": { "post": { "tags": [ "Finder" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } }, "get": { "tags": [ "Finder" ], "summary": "List the caller's bulk-finder jobs (paginated). GET /v1/finder/jobs", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/verify/single": { "post": { "tags": [ "Verify" ], "summary": "Verify a single email address (POST variant, email in request body).", "description": "Runs the full 10-step verification pipeline: syntax → normalize → did-you-mean →\r\nMX → disposable → free provider → role → SMTP → risk scorer → quality mapping.\r\n \r\n**Credit cost:** 1 credit for `ok`, `invalid`, `disposable`, `catch_all`.\r\n`unknown` and `error` results are **free**.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleVerifyRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SingleVerifyRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SingleVerifyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponseApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } }, "get": { "tags": [ "Verify" ], "summary": "Verify a single email address (GET variant, email as query parameter).", "description": "Identical to the POST variant. Example: `GET /v1/verify/single?email=user@example.com`", "parameters": [ { "name": "email", "in": "query", "description": "The email address to verify.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponseApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/verify/batch": { "post": { "tags": [ "Verify" ], "summary": "Verify up to 30 email addresses in a single request (interactive \"paste a batch\" path).", "description": "Addresses are de-duplicated (by canonical form) before probing, so the same address pasted twice\r\ncosts one credit. Each result follows the same credit rules as single verify. Send an\r\n`Idempotency-Key` header to make a retry replay the prior response with no re-charge.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchVerifyRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/BatchVerifyRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/BatchVerifyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchVerifyResponseApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/webhooks": { "get": { "tags": [ "Webhook" ], "summary": "List all webhooks for the authenticated user.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } }, "post": { "tags": [ "Webhook" ], "summary": "Create a new webhook endpoint. A signing secret is auto-generated.\r\nAt least one event type must be specified in the `events` array.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/webhooks/{id}": { "patch": { "tags": [ "Webhook" ], "summary": "Update a webhook's URL, events, or active status (partial update). Also handles toggle.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } }, "delete": { "tags": [ "Webhook" ], "summary": "Delete a webhook.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/webhooks/{id}/toggle": { "post": { "tags": [ "Webhook" ], "summary": "Update a webhook's URL, events, or active status (partial update). Also handles toggle.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhook" ], "summary": "Send a test delivery to verify the webhook URL is reachable.\r\nOnly active webhooks can be tested.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectApiResponse" } } } } } } } }, "components": { "schemas": { "ApiError": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string", "nullable": true }, "details": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "BatchSummary": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" }, "valid": { "type": "integer", "format": "int32" }, "invalid": { "type": "integer", "format": "int32" }, "catchAll": { "type": "integer", "format": "int32" }, "unknown": { "type": "integer", "format": "int32" }, "disposable": { "type": "integer", "format": "int32" }, "error": { "type": "integer", "format": "int32" }, "creditsCharged": { "type": "integer", "format": "int32" }, "creditsRemaining": { "type": "integer", "format": "int64" } }, "additionalProperties": false, "description": "Roll-up counts for a batch, so the UI can show a summary strip without recomputing." }, "BatchVerifyRequest": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false, "description": "Request body for POST /v1/verify/batch, up to 30 addresses." }, "BatchVerifyResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/VerifyResponse" }, "nullable": true }, "summary": { "$ref": "#/components/schemas/BatchSummary" } }, "additionalProperties": false, "description": "Result of POST /v1/verify/batch, up to 30 addresses validated in one request." }, "BatchVerifyResponseApiResponse": { "type": "object", "properties": { "status": { "type": "string", "nullable": true, "readOnly": true }, "data": { "$ref": "#/components/schemas/BatchVerifyResponse" }, "error": { "$ref": "#/components/schemas/ApiError" } }, "additionalProperties": false }, "CreateWebhookRequest": { "required": [ "events", "url" ], "type": "object", "properties": { "url": { "maxLength": 2048, "minLength": 0, "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "isActive": { "type": "boolean" } }, "additionalProperties": false }, "CreditTransactionType": { "enum": [ 1, 2, 3, 4 ], "type": "integer", "format": "int32" }, "FinderBatchRequest": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/FinderRequest" }, "nullable": true } }, "additionalProperties": false, "description": "Request body for POST /v1/finder/batch, up to 100 contacts in one call." }, "FinderRequest": { "type": "object", "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Request body for POST /v1/finder/single. First or last name is required; domain is required." }, "FinderResponse": { "type": "object", "properties": { "email": { "type": "string", "description": "The found email address, or null when nothing usable was found.", "nullable": true, "example": "jane.doe@acme.com" }, "status": { "type": "string", "description": "Whether an address was returned: `Found` or `Not Found`.", "nullable": true, "example": "Found" }, "quality": { "type": "string", "description": "Send-readiness of the found address: `Good`, `Risky`, or `Bad`.", "nullable": true, "example": "Good" }, "result": { "type": "string", "description": "`Ok` (verified deliverable), `Catch-all` (the domain accepts it), or `Unknown`.", "nullable": true, "example": "Ok" }, "reason": { "type": "string", "description": "Internal reason for the outcome, e.g. `found`, `catch_all`, `not_found`, `unsupported_free_domain`.", "nullable": true, "example": "found" }, "confidence": { "type": "integer", "description": "Confidence in the format for this person on this domain, 0 to 100.", "format": "int32", "example": 92 }, "provider": { "type": "string", "description": "The domain's mailbox provider when detected, e.g. `google`, `microsoft`. Empty otherwise.", "nullable": true, "example": "google" }, "creditsCharged": { "type": "integer", "description": "Credits charged for this call: `10` when an email is returned, `0` on a miss.", "format": "int32", "example": 10 }, "creditsRemaining": { "type": "integer", "description": "Your remaining credit balance after this call.", "format": "int64", "example": 48200 } }, "additionalProperties": false, "description": "Tenant-facing result of an email find (`POST /v1/finder`). Charged 10 credits only when a usable\r\naddress is returned; a miss is free. Shared by the REST API, the batch endpoint, and the MCP find tool." }, "FinderResponseApiResponse": { "type": "object", "properties": { "status": { "type": "string", "nullable": true, "readOnly": true }, "data": { "$ref": "#/components/schemas/FinderResponse" }, "error": { "$ref": "#/components/schemas/ApiError" } }, "additionalProperties": false }, "ObjectApiResponse": { "type": "object", "properties": { "status": { "type": "string", "nullable": true, "readOnly": true }, "data": { "nullable": true, "readOnly": true }, "error": { "$ref": "#/components/schemas/ApiError" } }, "additionalProperties": false }, "Order": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "userId": { "type": "integer", "format": "int64" }, "packageId": { "type": "integer", "format": "int32", "nullable": true }, "creditsPurchased": { "type": "integer", "format": "int64" }, "bonusCredits": { "type": "integer", "format": "int64" }, "totalCreditsAdded": { "type": "integer", "format": "int64" }, "amountUsd": { "type": "number", "format": "double" }, "discountUsd": { "type": "number", "format": "double" }, "finalAmountUsd": { "type": "number", "format": "double" }, "unitPriceUsd": { "type": "number", "format": "double", "nullable": true }, "promotionId": { "type": "integer", "format": "int32", "nullable": true }, "stripePaymentIntentId": { "type": "string", "nullable": true }, "stripeChargeId": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "failureReason": { "type": "string", "nullable": true }, "invoiceNumber": { "type": "string", "nullable": true }, "isAutoTopup": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "OrderPagedResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "nullable": true }, "page": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" }, "totalPages": { "type": "integer", "format": "int32", "readOnly": true } }, "additionalProperties": false }, "OrderPagedResultApiResponse": { "type": "object", "properties": { "status": { "type": "string", "nullable": true, "readOnly": true }, "data": { "$ref": "#/components/schemas/OrderPagedResult" }, "error": { "$ref": "#/components/schemas/ApiError" } }, "additionalProperties": false }, "OrderStatus": { "enum": [ 1, 2, 3, 4, 5 ], "type": "integer", "format": "int32" }, "SingleVerifyRequest": { "type": "object", "properties": { "email": { "type": "string", "nullable": true } }, "additionalProperties": false, "description": "Request body for POST /v1/verify/single." }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "maxLength": 2048, "minLength": 0, "type": "string", "format": "uri", "nullable": true }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "nullable": true }, "isActive": { "type": "boolean", "nullable": true } }, "additionalProperties": false }, "VerifyResponse": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address that was verified, echoed back from your request.", "nullable": true, "example": "jane.doe@acme.com" }, "result": { "type": "string", "description": "Headline verdict: one of `ok`, `invalid`, `catch_all`, `unknown`, `disposable`, or `error`.", "nullable": true, "example": "ok" }, "resultCode": { "type": "integer", "description": "Numeric form of `result`: 1 ok, 2 catch_all, 3 unknown, 4 error, 5 disposable, 6 invalid.", "format": "int32", "example": 1 }, "subResult": { "type": "string", "description": "Precise reason from the mail server, from the public sub-result set (`ok`, `greylisted`, `ip_blocked`, `mailbox_full`, `no_mailbox`, `invalid_syntax`, `dns_error`, `timeout`, ...). Null when there is none.", "nullable": true, "example": "ok" }, "quality": { "type": "string", "description": "One-word send recommendation: `good`, `risky`, or `bad`. Empty for an `error` result.", "nullable": true, "example": "good" }, "free": { "type": "boolean", "description": "True when the address is on a free consumer provider such as gmail.com or yahoo.com.", "example": false }, "role": { "type": "boolean", "description": "True when this is a role address (info@, support@, sales@) rather than a person.", "example": false }, "disposable": { "type": "boolean", "description": "True when the domain is a throwaway or temporary-inbox provider.", "example": false }, "catchAll": { "type": "boolean", "description": "True when the domain accepts every recipient, so the exact mailbox cannot be isolated.", "example": false }, "didYouMean": { "type": "string", "description": "A suggested correction when the address looks mistyped (gmial.com becomes gmail.com). Null when nothing looks wrong.", "nullable": true, "example": "jane.doe@gmail.com" }, "provider": { "type": "string", "description": "The mailbox provider when detected (`google`, `microsoft`, `yahoo`, ...). Empty if unknown.", "nullable": true, "example": "google" }, "antiSpam": { "type": "boolean", "description": "True when a security or anti-spam gateway (Proofpoint, Mimecast, Barracuda) sits in front of the domain.", "example": false }, "riskScore": { "type": "integer", "description": "Graded risk from 0 to 100, banded to match `quality`: 0 to 29 good (safe to send), 30 to 69 risky, 70 to 100 bad. Lower is safer.", "format": "int32", "example": 5 }, "creditsCharged": { "type": "integer", "description": "Credits charged for this call: 1 on a decisive result (ok, catch_all, disposable, invalid), 0 on unknown or error.", "format": "int32", "example": 1 }, "creditsRemaining": { "type": "integer", "description": "Your remaining credit balance after this call.", "format": "int64", "example": 49999 }, "executionMs": { "type": "integer", "description": "How long the verification took, in milliseconds.", "format": "int32", "example": 420 } }, "additionalProperties": false, "description": "Result of `POST /v1/verify`: the deliverability verdict for a single address, plus the signal\r\nflags, a graded risk score, and the credits charged. Shared by the REST API, the batch endpoint, the\r\nMCP verify tool, and the Zapier/Make/n8n actions, so every channel returns an identical shape." }, "VerifyResponseApiResponse": { "type": "object", "properties": { "status": { "type": "string", "nullable": true, "readOnly": true }, "data": { "$ref": "#/components/schemas/VerifyResponse" }, "error": { "$ref": "#/components/schemas/ApiError" } }, "additionalProperties": false }, "WebhookEvent": { "enum": [ 1, 2, 4, 8 ], "type": "integer", "format": "int32" } }, "securitySchemes": { "X-API-KEY": { "type": "apiKey", "description": "Your API key. Obtain it after registration and OTP verification.", "name": "X-API-KEY", "in": "header" } } }, "security": [ { "X-API-KEY": [ ] } ] }