{ "openapi": "3.1.0", "info": { "title": "VerifyInbox API", "description": "B2B contact data: find business email addresses, verify them, and enrich them — with a citation for every address and an explainable score for every verdict.\n\nGenerated from the server's own Zod route schemas — the same objects that validate requests and serialize responses — so this contract cannot drift from what the API accepts. Staff-only administrative paths and the billing webhook are removed from this published copy; everything a customer can call is here.\n\nPlain-text product brief for agents: https://verifyinbox.tech/llms.txt · Full reference: https://verifyinbox.tech/llms-full.txt · Documentation: https://verifyinbox.tech/docs", "version": "1.0.0", "contact": { "name": "VerifyInbox", "url": "https://verifyinbox.tech/contact" }, "termsOfService": "https://verifyinbox.tech/terms" }, "components": { "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "att_session", "description": "Session cookie set by the dashboard sign-in flow." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key created in the dashboard: `Authorization: Bearer att_live_…`" } }, "schemas": {} }, "paths": { "/healthz/live": { "get": { "summary": "Liveness probe", "tags": [ "health" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "uptimeSeconds": { "type": "number" } }, "required": [ "status", "uptimeSeconds" ], "additionalProperties": false } } } } } } }, "/healthz/ready": { "get": { "summary": "Readiness probe — checks Mongo and Redis", "tags": [ "health" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "checks": { "type": "object", "properties": { "mongo": { "type": "boolean" }, "redis": { "type": "boolean" } }, "required": [ "mongo", "redis" ], "additionalProperties": false } }, "required": [ "status", "checks" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "degraded" ] }, "checks": { "type": "object", "properties": { "mongo": { "type": "boolean" }, "redis": { "type": "boolean" } }, "required": [ "mongo", "redis" ], "additionalProperties": false } }, "required": [ "status", "checks" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/signup": { "post": { "summary": "Create an account and its first organization", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Account email address" }, "password": { "type": "string", "minLength": 10, "maxLength": 200, "description": "At least 10 characters. No composition rules — length is what matters." }, "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationName": { "type": "string", "minLength": 1, "maxLength": 80 }, "turnstileToken": { "type": "string", "maxLength": 4000 } }, "required": [ "email", "password", "displayName" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "organizationId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "verificationEmailSent": { "type": "boolean" }, "emailVerificationRequired": { "type": "boolean" }, "grantedCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "businessBonusApplied": { "type": "boolean" } }, "required": [ "userId", "organizationId", "verificationEmailSent", "emailVerificationRequired", "grantedCreditsMilli", "businessBonusApplied" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/login": { "post": { "summary": "Sign in with an email address and password", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Account email address" }, "password": { "type": "string", "minLength": 1, "maxLength": 200 }, "turnstileToken": { "type": "string", "maxLength": 4000 } }, "required": [ "email", "password" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/logout": { "post": { "summary": "Revoke the current session", "tags": [ "auth" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/session": { "get": { "summary": "Who am I, which organization am I in, and what may I do", "tags": [ "auth" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerified": { "type": "boolean" }, "twoFactorEnabled": { "type": "boolean" }, "mustChangePassword": { "type": "boolean" }, "isStaff": { "type": "boolean" } }, "required": [ "id", "email", "displayName", "avatarUrl", "emailVerified", "twoFactorEnabled", "mustChangePassword", "isStaff" ], "additionalProperties": false }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "starter", "growth", "scale", "enterprise" ] }, "creditBalanceMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "currentPeriodEndsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] } }, "required": [ "id", "name", "slug", "plan", "creditBalanceMilli", "currentPeriodEndsAt" ], "additionalProperties": false }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "slug": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } } }, "required": [ "id", "name", "slug", "roles" ], "additionalProperties": false } }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "org.read", "org.manage", "org.billing", "member.read", "member.invite", "member.manage", "verify.run", "verify.bulk", "discovery.search", "results.read", "leads.read", "leads.write", "leads.delete", "apikey.read", "apikey.manage", "webhook.read", "webhook.manage", "suppression.read", "suppression.manage", "usage.read", "audit.read", "admin.read", "admin.manage" ] } }, "authMethod": { "type": "string", "enum": [ "session", "api_key" ] }, "emailVerificationRequired": { "type": "boolean" } }, "required": [ "user", "organization", "organizations", "roles", "permissions", "authMethod", "emailVerificationRequired" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/config": { "get": { "summary": "What the sign-in screen needs to render", "tags": [ "auth" ], "description": "Which providers are enabled, the public challenge key, and whether a new account must confirm its address. Nothing here is secret.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "oauth": { "type": "object", "properties": { "google": { "type": "boolean" }, "github": { "type": "boolean" } }, "required": [ "google", "github" ], "additionalProperties": false }, "turnstileSiteKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerificationRequired": { "type": "boolean" } }, "required": [ "oauth", "turnstileSiteKey", "emailVerificationRequired" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/oauth/{provider}": { "get": { "summary": "Begin Google or GitHub sign-in", "tags": [ "auth" ], "parameters": [ { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "returnTo", "required": false }, { "schema": { "type": "string", "enum": [ "google", "github" ] }, "in": "path", "name": "provider", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/oauth/{provider}/callback": { "get": { "summary": "Complete Google or GitHub sign-in", "tags": [ "auth" ], "parameters": [ { "schema": { "type": "string", "maxLength": 2048 }, "in": "query", "name": "code", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "error", "required": false }, { "schema": { "type": "string", "enum": [ "google", "github" ] }, "in": "path", "name": "provider", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/profile": { "patch": { "summary": "Change your display name", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "displayName" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerified": { "type": "boolean" }, "twoFactorEnabled": { "type": "boolean" }, "mustChangePassword": { "type": "boolean" }, "isStaff": { "type": "boolean" } }, "required": [ "id", "email", "displayName", "avatarUrl", "emailVerified", "twoFactorEnabled", "mustChangePassword", "isStaff" ], "additionalProperties": false }, "organization": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "starter", "growth", "scale", "enterprise" ] }, "creditBalanceMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "currentPeriodEndsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] } }, "required": [ "id", "name", "slug", "plan", "creditBalanceMilli", "currentPeriodEndsAt" ], "additionalProperties": false }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "slug": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } } }, "required": [ "id", "name", "slug", "roles" ], "additionalProperties": false } }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "org.read", "org.manage", "org.billing", "member.read", "member.invite", "member.manage", "verify.run", "verify.bulk", "discovery.search", "results.read", "leads.read", "leads.write", "leads.delete", "apikey.read", "apikey.manage", "webhook.read", "webhook.manage", "suppression.read", "suppression.manage", "usage.read", "audit.read", "admin.read", "admin.manage" ] } }, "authMethod": { "type": "string", "enum": [ "session", "api_key" ] }, "emailVerificationRequired": { "type": "boolean" } }, "required": [ "user", "organization", "organizations", "roles", "permissions", "authMethod", "emailVerificationRequired" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/password": { "post": { "summary": "Change your password and sign out every other session", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "maxLength": 200 }, "newPassword": { "type": "string", "minLength": 10, "maxLength": 200, "description": "At least 10 characters. No composition rules — length is what matters." } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "revokedSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "ok", "revokedSessions" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/password/reset-request": { "post": { "summary": "Send a password-reset link", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Account email address" }, "turnstileToken": { "type": "string", "maxLength": 4000 } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/password/reset": { "post": { "summary": "Complete a password reset", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 200 }, "newPassword": { "type": "string", "minLength": 10, "maxLength": 200, "description": "At least 10 characters. No composition rules — length is what matters." } }, "required": [ "token", "newPassword" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/email/verify": { "post": { "summary": "Confirm an email address from a link", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 200 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/email/verify/resend": { "post": { "summary": "Send the confirmation link again", "tags": [ "auth" ], "description": "Invalidates any earlier link. Answers `alreadyVerified` rather than an error when there is nothing to confirm, so a stale tab does not show a failure.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "alreadyVerified": { "type": "boolean" }, "sent": { "type": "boolean" } }, "required": [ "alreadyVerified", "sent" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/sessions": { "get": { "summary": "List your active sessions", "tags": [ "auth" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "userAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSeenAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "current": { "type": "boolean" } }, "required": [ "id", "userAgent", "ip", "lastSeenAt", "createdAt", "current" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/sessions/{sessionId}": { "delete": { "summary": "Sign out one of your other devices", "tags": [ "auth" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/auth/organizations": { "get": { "summary": "Organizations you can switch to", "tags": [ "auth" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": {} } } }, "required": [ "items" ], "additionalProperties": {} } } } } } } }, "/api/v1/organization": { "get": { "summary": "The organization you are currently acting in", "tags": [ "organizations" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "starter", "growth", "scale", "enterprise" ] }, "creditBalanceMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "currentPeriodEndsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] }, "seatsUsed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "seatLimit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "name", "slug", "plan", "creditBalanceMilli", "currentPeriodEndsAt", "seatsUsed", "seatLimit", "createdAt" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Rename the organization", "tags": [ "organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/organization/switch": { "post": { "summary": "Point this session at another organization you belong to", "tags": [ "organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" } }, "required": [ "organizationId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/organization/members": { "get": { "summary": "List members", "tags": [ "organizations" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } }, "lastLoginAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] }, "joinedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "userId", "email", "displayName", "avatarUrl", "roles", "lastLoginAt", "joinedAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } } } } }, "/api/v1/organization/members/{userId}": { "patch": { "summary": "Change a member's roles", "tags": [ "organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } } }, "required": [ "roles" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "userId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Remove a member", "tags": [ "organizations" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "userId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/organization/invites": { "get": { "summary": "List pending invitations", "tags": [ "organizations" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } }, "invitedByUserId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "email", "roles", "invitedByUserId", "expiresAt", "createdAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } } } }, "post": { "summary": "Invite someone to the organization", "tags": [ "organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "roles": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } } }, "required": [ "email", "roles" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "inviteEmailSent": { "type": "boolean" } }, "required": [ "id", "email", "roles", "expiresAt", "inviteEmailSent" ], "additionalProperties": false } } } } } } }, "/api/v1/organization/invites/{inviteId}": { "delete": { "summary": "Revoke a pending invitation", "tags": [ "organizations" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "inviteId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/organization/invites/accept": { "post": { "summary": "Accept an invitation", "tags": [ "organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 200 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } } }, "required": [ "organizationId", "roles" ], "additionalProperties": false } } } } } } }, "/api/v1/credits": { "get": { "summary": "Current balance", "tags": [ "credits" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "balanceMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "balance": { "type": "number" } }, "required": [ "balanceMilli", "balance" ], "additionalProperties": false } } } } } } }, "/api/v1/credits/ledger": { "get": { "summary": "Every credit movement, newest first", "tags": [ "credits" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "deltaMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "balanceAfterMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "reason": { "type": "string" }, "operation": { "anyOf": [ { "type": "string", "enum": [ "verify", "verify_bulk_row", "email_finder", "domain_search", "company", "combined", "email_count" ] }, { "type": "null" } ] }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "deltaMilli", "balanceAfterMilli", "reason", "operation", "ref", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } } } } } }, "/api/v1/usage": { "get": { "summary": "Daily usage, for the charts", "tags": [ "credits" ], "parameters": [ { "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 365 }, "in": "query", "name": "days", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "summary": { "type": "object", "properties": { "totalCalls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "byOperation": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "calls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "creditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "calls", "creditsMilli" ], "additionalProperties": false } } }, "required": [ "totalCalls", "totalCreditsMilli", "byOperation" ], "additionalProperties": false }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "operation": { "type": "string", "enum": [ "verify", "verify_bulk_row", "email_finder", "domain_search", "company", "combined", "email_count" ] }, "calls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "creditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "refundedCalls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "day", "operation", "calls", "creditsMilli", "refundedCalls" ], "additionalProperties": false } } }, "required": [ "from", "to", "summary", "days" ], "additionalProperties": false } } } } } } }, "/api/v1/pricing": { "get": { "summary": "Plans, credit packs and per-operation costs", "tags": [ "credits" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/verify": { "post": { "summary": "Verify one email address", "tags": [ "verify" ], "description": "Costs 0.5 credits. A result with `retryable: true` means the mailbox was never tested — it is not charged, and it must not be treated as undeliverable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 254, "description": "Email address to verify — validated by the engine, not at the edge" } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "status": { "type": "string", "enum": [ "deliverable", "undeliverable", "unknown" ] }, "reason": { "type": "string" }, "result": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "email", "status", "reason", "result" ], "additionalProperties": false } } } } } } }, "/api/v1/verifications": { "get": { "summary": "Verifications this organization has run", "tags": [ "verify" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "enum": [ "deliverable", "undeliverable", "unknown" ] }, "in": "query", "name": "status", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "domain": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "description": "Domain name, e.g. acme.com" }, "status": { "type": "string", "enum": [ "deliverable", "undeliverable", "unknown" ] }, "reason": { "type": "string" }, "verifiedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "email", "domain", "status", "reason", "verifiedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } } } } } }, "/api/v1/domain-search": { "get": { "summary": "Every indexed address at a domain, with citations", "tags": [ "discovery" ], "description": "Costs 1 credit, refunded when the domain has no indexed addresses. Each contact carries the pages it was found on, when each was last seen, and whether the address is still published there.", "parameters": [ { "schema": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$" }, "in": "query", "name": "domain", "required": true, "description": "Domain name, e.g. acme.com" }, { "schema": { "type": "string", "enum": [ "personal", "generic" ] }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "string", "enum": [ "engineering", "sales", "marketing", "support", "hr", "finance", "legal", "product", "operations", "executive", "medical", "education" ] }, "in": "query", "name": "department", "required": false }, { "schema": { "type": "string", "enum": [ "executive", "senior", "manager", "senior_ic", "junior", "individual" ] }, "in": "query", "name": "seniority", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "in": "query", "name": "minConfidence", "required": false }, { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "crawl", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/email-finder": { "get": { "summary": "Find a person's address from their name and company domain", "tags": [ "discovery" ], "description": "Costs 1 credit, refunded when no address is found. `verify=false` skips the SMTP probe and caps confidence at 70.", "parameters": [ { "schema": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$" }, "in": "query", "name": "domain", "required": true, "description": "Domain name, e.g. acme.com" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "in": "query", "name": "first_name", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "in": "query", "name": "last_name", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 160 }, "in": "query", "name": "full_name", "required": false }, { "schema": { "default": true, "type": "boolean" }, "in": "query", "name": "verify", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/company": { "get": { "summary": "Company profile for a domain", "tags": [ "discovery" ], "description": "Costs 1 credit, refunded when the domain is not indexed.", "parameters": [ { "schema": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$" }, "in": "query", "name": "domain", "required": true, "description": "Domain name, e.g. acme.com" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/email-count": { "get": { "summary": "How many addresses are indexed for a domain", "tags": [ "discovery" ], "description": "Free. Ask before you decide to pay — charging for this answer only makes callers guess, and a wrong guess costs a crawl anyway.", "parameters": [ { "schema": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$" }, "in": "query", "name": "domain", "required": true, "description": "Domain name, e.g. acme.com" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/bulk/upload": { "post": { "summary": "Upload a CSV and stage a job for column mapping", "tags": [ "verify" ], "description": "Reserves nothing and queues nothing. Returns the parsed headers, a preview and the exact cost, so the mapping can be confirmed before any credit is spent.", "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "headers": { "type": "array", "items": { "type": "string" } }, "preview": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "totalRows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "uniqueRows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "suggestedEmailColumn": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "estimatedCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." } }, "required": [ "jobId", "headers", "preview", "totalRows", "uniqueRows", "suggestedEmailColumn", "estimatedCreditsMilli" ], "additionalProperties": false } } } } } } }, "/api/v1/bulk/{jobId}/confirm": { "post": { "summary": "Approve the column mapping, reserve credits and queue the job", "tags": [ "verify" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailColumn": { "type": "integer", "minimum": 0, "maximum": 500 } }, "required": [ "emailColumn" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "jobId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "mapping", "queued", "running", "completed", "failed", "canceled" ] }, "totals": { "type": "object", "properties": { "rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deliverable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "undeliverable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unknown": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "rows", "unique", "processed", "deliverable", "undeliverable", "unknown", "failed" ], "additionalProperties": false }, "estimatedCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "actualCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] } }, "required": [ "id", "name", "status", "totals", "estimatedCreditsMilli", "actualCreditsMilli", "createdAt", "completedAt" ], "additionalProperties": false } } } } } } }, "/api/v1/bulk/{jobId}/cancel": { "post": { "summary": "Stop a job and release the credits it has not spent", "tags": [ "verify" ], "description": "Rows that already produced a verdict are charged; the rest of the reservation is returned. Refused once a job has finished.", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "jobId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "mapping", "queued", "running", "completed", "failed", "canceled" ] }, "totals": { "type": "object", "properties": { "rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deliverable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "undeliverable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unknown": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "rows", "unique", "processed", "deliverable", "undeliverable", "unknown", "failed" ], "additionalProperties": false }, "estimatedCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "actualCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] } }, "required": [ "id", "name", "status", "totals", "estimatedCreditsMilli", "actualCreditsMilli", "createdAt", "completedAt" ], "additionalProperties": false } } } } } } }, "/api/v1/bulk": { "get": { "summary": "Bulk jobs for this organization", "tags": [ "verify" ], "parameters": [ { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "mapping", "queued", "running", "completed", "failed", "canceled" ] }, "totals": { "type": "object", "properties": { "rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deliverable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "undeliverable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unknown": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "rows", "unique", "processed", "deliverable", "undeliverable", "unknown", "failed" ], "additionalProperties": false }, "estimatedCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "actualCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] } }, "required": [ "id", "name", "status", "totals", "estimatedCreditsMilli", "actualCreditsMilli", "createdAt", "completedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } } } } } }, "/api/v1/bulk/{jobId}": { "get": { "summary": "One job, with live progress counters", "tags": [ "verify" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "jobId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "mapping", "queued", "running", "completed", "failed", "canceled" ] }, "totals": { "type": "object", "properties": { "rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "processed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deliverable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "undeliverable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unknown": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "rows", "unique", "processed", "deliverable", "undeliverable", "unknown", "failed" ], "additionalProperties": false }, "estimatedCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "actualCreditsMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] } }, "required": [ "id", "name", "status", "totals", "estimatedCreditsMilli", "actualCreditsMilli", "createdAt", "completedAt" ], "additionalProperties": false } } } } } } }, "/api/v1/bulk/{jobId}/export": { "get": { "summary": "Download results as CSV — the original columns, plus our verdicts", "tags": [ "verify" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "jobId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/api-keys": { "get": { "summary": "Active API keys", "tags": [ "api-keys" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "displayPrefix": { "type": "string" }, "last4": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "org.read", "org.manage", "org.billing", "member.read", "member.invite", "member.manage", "verify.run", "verify.bulk", "discovery.search", "results.read", "leads.read", "leads.write", "leads.delete", "apikey.read", "apikey.manage", "webhook.read", "webhook.manage", "suppression.read", "suppression.manage", "usage.read", "audit.read", "admin.read", "admin.manage" ] } }, "rateLimitPerMinute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "usage": { "type": "object", "properties": { "totalCalls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "successfulCalls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failedCalls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "creditsUsedMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits × 1000. A single verify costs 500." }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] } }, "required": [ "totalCalls", "successfulCalls", "failedCalls", "creditsUsedMilli", "lastUsedAt" ], "additionalProperties": false }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "name", "mode", "displayPrefix", "last4", "scopes", "rateLimitPerMinute", "usage", "expiresAt", "createdAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } } } }, "post": { "summary": "Create an API key", "tags": [ "api-keys" ], "description": "The plaintext key is returned once and never again. A key can never exceed its creator's permissions — its scopes are intersected with their live grants on every request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "mode": { "default": "live", "type": "string", "enum": [ "live", "test" ] }, "scopes": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "enum": [ "org.read", "org.manage", "org.billing", "member.read", "member.invite", "member.manage", "verify.run", "verify.bulk", "discovery.search", "results.read", "leads.read", "leads.write", "leads.delete", "apikey.read", "apikey.manage", "webhook.read", "webhook.manage", "suppression.read", "suppression.manage", "usage.read", "audit.read", "admin.read", "admin.manage" ] } }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "required": [ "name", "scopes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "key": { "type": "string", "description": "Shown once. Copy it now — only a hash is stored." }, "displayPrefix": { "type": "string" }, "last4": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "org.read", "org.manage", "org.billing", "member.read", "member.invite", "member.manage", "verify.run", "verify.bulk", "discovery.search", "results.read", "leads.read", "leads.write", "leads.delete", "apikey.read", "apikey.manage", "webhook.read", "webhook.manage", "suppression.read", "suppression.manage", "usage.read", "audit.read", "admin.read", "admin.manage" ] } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "name", "key", "displayPrefix", "last4", "scopes", "mode", "createdAt" ], "additionalProperties": false } } } } } } }, "/api/v1/api-keys/{keyId}": { "delete": { "summary": "Revoke an API key", "tags": [ "api-keys" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "keyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/webhooks": { "get": { "summary": "Webhook endpoints", "tags": [ "webhooks" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "displayPrefix": { "type": "string" }, "enabled": { "type": "boolean" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lastSuccessAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] }, "lastFailureAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "url", "events", "displayPrefix", "enabled", "failureCount", "lastSuccessAt", "lastFailureAt", "createdAt" ], "additionalProperties": false } }, "availableEvents": { "type": "array", "items": { "type": "string" } } }, "required": [ "items", "availableEvents" ], "additionalProperties": false } } } } } }, "post": { "summary": "Add a webhook endpoint", "tags": [ "webhooks" ], "description": "The signing secret is returned once. Deliveries are signed `sha256=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "verification.completed", "bulk_job.completed", "bulk_job.failed", "credits.low", "credits.exhausted" ] } } }, "required": [ "url", "events" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "description": "Shown once. Used to verify our signature." }, "displayPrefix": { "type": "string" } }, "required": [ "id", "url", "events", "secret", "displayPrefix" ], "additionalProperties": false } } } } } } }, "/api/v1/webhooks/{endpointId}": { "delete": { "summary": "Remove a webhook endpoint", "tags": [ "webhooks" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "endpointId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/webhooks/{endpointId}/deliveries": { "get": { "summary": "Recent delivery attempts, for debugging", "tags": [ "webhooks" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "endpointId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "event": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "responseStatus": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "responseBody": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, { "type": "null" } ] } }, "required": [ "id", "event", "status", "attempts", "responseStatus", "responseBody", "createdAt", "deliveredAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } } } } }, "/api/v1/leads": { "get": { "summary": "Saved leads", "tags": [ "leads" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "query", "name": "listId", "required": false, "description": "Opaque resource id" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "tags", "required": false, "description": "Comma-separated. A lead must carry all of them." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string", "enum": [ "engineering", "sales", "marketing", "support", "hr", "finance", "legal", "product", "operations", "executive", "medical", "education" ] }, { "type": "null" } ] }, "seniority": { "anyOf": [ { "type": "string", "enum": [ "executive", "senior", "manager", "senior_ic", "junior", "individual" ] }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "personal", "generic" ] }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nameSource": { "anyOf": [ { "type": "string", "enum": [ "jsonld", "microdata", "proximity", "local_part" ] }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "format": "uri" }, "domain": { "type": "string" }, "method": { "anyOf": [ { "type": "string", "enum": [ "mailto", "cfemail", "obfuscated", "text" ] }, { "type": "null" } ] }, "extractedOn": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "lastSeenOn": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "stillOnPage": { "type": "boolean" } }, "required": [ "uri", "domain", "method", "extractedOn", "lastSeenOn", "stillOnPage" ], "additionalProperties": false } }, "lastVerification": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "deliverable", "undeliverable", "unknown" ] }, "reason": { "type": "string" }, "verifiedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "status", "reason", "verifiedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "listIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" } }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "email", "firstName", "lastName", "position", "department", "seniority", "type", "companyName", "linkedinUrl", "phone", "confidence", "nameSource", "sources", "lastVerification", "listIds", "tags", "notes", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } } } } }, "post": { "summary": "Save a lead, merging into an existing one at the same address", "tags": [ "leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 254 }, "listIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" } }, "firstName": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string", "enum": [ "engineering", "sales", "marketing", "support", "hr", "finance", "legal", "product", "operations", "executive", "medical", "education" ] }, { "type": "null" } ] }, "seniority": { "anyOf": [ { "type": "string", "enum": [ "executive", "senior", "manager", "senior_ic", "junior", "individual" ] }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "personal", "generic" ] }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "nameSource": { "anyOf": [ { "type": "string", "enum": [ "jsonld", "microdata", "proximity", "local_part" ] }, { "type": "null" } ] }, "sources": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "format": "uri" }, "domain": { "type": "string" }, "method": { "anyOf": [ { "type": "string", "enum": [ "mailto", "cfemail", "obfuscated", "text" ] }, { "type": "null" } ] }, "extractedOn": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "lastSeenOn": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "stillOnPage": { "type": "boolean" } }, "required": [ "uri", "domain", "method", "extractedOn", "lastSeenOn", "stillOnPage" ], "additionalProperties": false } }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "email": { "type": "string" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string", "enum": [ "engineering", "sales", "marketing", "support", "hr", "finance", "legal", "product", "operations", "executive", "medical", "education" ] }, { "type": "null" } ] }, "seniority": { "anyOf": [ { "type": "string", "enum": [ "executive", "senior", "manager", "senior_ic", "junior", "individual" ] }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "personal", "generic" ] }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nameSource": { "anyOf": [ { "type": "string", "enum": [ "jsonld", "microdata", "proximity", "local_part" ] }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "format": "uri" }, "domain": { "type": "string" }, "method": { "anyOf": [ { "type": "string", "enum": [ "mailto", "cfemail", "obfuscated", "text" ] }, { "type": "null" } ] }, "extractedOn": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "lastSeenOn": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" }, "stillOnPage": { "type": "boolean" } }, "required": [ "uri", "domain", "method", "extractedOn", "lastSeenOn", "stillOnPage" ], "additionalProperties": false } }, "lastVerification": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "deliverable", "undeliverable", "unknown" ] }, "reason": { "type": "string" }, "verifiedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "status", "reason", "verifiedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "listIds": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" } }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "email", "firstName", "lastName", "position", "department", "seniority", "type", "companyName", "linkedinUrl", "phone", "confidence", "nameSource", "sources", "lastVerification", "listIds", "tags", "notes", "createdAt" ], "additionalProperties": false } } } } } } }, "/api/v1/leads/{leadId}": { "delete": { "summary": "Delete a lead", "tags": [ "leads" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "leadId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/leads/export": { "get": { "summary": "Export leads as CSV, with their citations", "tags": [ "leads" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "query", "name": "listId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "in": "query", "name": "search", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/lead-lists": { "get": { "summary": "Lead lists", "tags": [ "leads" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leadCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "name", "description", "leadCount", "createdAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } } } }, "post": { "summary": "Create a list", "tags": [ "leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "name": { "type": "string" }, "leadCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "leadCount" ], "additionalProperties": false } } } } } } }, "/api/v1/lead-lists/{listId}": { "delete": { "summary": "Delete a list — the leads in it survive", "tags": [ "leads" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "in": "path", "name": "listId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/api/v1/tools/verify": { "post": { "summary": "Free single-address verification", "tags": [ "tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "turnstileToken": { "type": "string", "maxLength": 4000 }, "email": { "type": "string", "minLength": 3, "maxLength": 254, "description": "Email address to verify — validated by the engine, not at the edge" } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/tools/email-finder": { "post": { "summary": "Free email finder", "tags": [ "tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "turnstileToken": { "type": "string", "maxLength": 4000 }, "domain": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "description": "Domain name, e.g. acme.com" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 80 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "domain", "firstName", "lastName" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/tools/domain-search": { "post": { "summary": "Free domain search — a five-row preview with citations", "tags": [ "tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "turnstileToken": { "type": "string", "maxLength": 4000 }, "domain": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "description": "Domain name, e.g. acme.com" } }, "required": [ "domain" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/tools/email-count": { "post": { "summary": "How many addresses are indexed for a domain — free everywhere", "tags": [ "tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "description": "Domain name, e.g. acme.com" } }, "required": [ "domain" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/tools/suppression": { "post": { "summary": "Erase an address or domain and keep it out of future crawls", "tags": [ "compliance" ], "description": "Erases matching records immediately and adds the value to a permanent suppression list enforced on both the crawl path and every read path, so the record cannot reappear the next time the source page is read.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "email", "domain" ] }, "value": { "type": "string", "minLength": 3, "maxLength": 254 }, "reason": { "type": "string", "maxLength": 80 } }, "required": [ "scope", "value" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/tools/dns": { "post": { "summary": "MX, SPF, DMARC and DKIM records for a domain", "tags": [ "tools" ], "description": "Answered from DNS directly rather than through the engine — these are public records and cost no sending capacity.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "turnstileToken": { "type": "string", "maxLength": 4000 }, "domain": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$", "description": "Domain name, e.g. acme.com" } }, "required": [ "domain" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/mcp": { "post": { "summary": "Model Context Protocol endpoint (JSON-RPC 2.0)", "tags": [ "mcp" ], "description": "Exposes verification and discovery as MCP tools. Authenticate with a normal API key; calls spend that key's credits under its own scopes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "method": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "jsonrpc", "method" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } } }, "/api/v1/billing/checkout": { "post": { "summary": "Start a checkout for a credit pack or a plan", "tags": [ "billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packId": { "type": "string", "minLength": 1, "maxLength": 40 }, "planId": { "type": "string", "enum": [ "free", "starter", "growth", "scale", "enterprise" ] }, "interval": { "type": "string", "enum": [ "monthly", "annual" ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "priceId": { "type": "string" }, "customData": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "clientToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "orderId", "priceId", "customData", "clientToken", "environment" ], "additionalProperties": false } } } } } } }, "/api/v1/billing/orders": { "get": { "summary": "Purchase history", "tags": [ "billing" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{24}$", "description": "Opaque resource id" }, "kind": { "type": "string", "enum": [ "subscription", "credit_pack" ] }, "amountCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "refunded" ] }, "creditsGrantedMilli": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "invoiceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC timestamp" } }, "required": [ "id", "kind", "amountCents", "currency", "status", "creditsGrantedMilli", "invoiceUrl", "createdAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } } } } }, "/api/v1/billing/cancel": { "post": { "summary": "Cancel the subscription at the end of the current period", "tags": [ "billing" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } } } } } }, "servers": [ { "url": "https://app.verifyinbox.tech", "description": "Production" } ], "tags": [ { "name": "health", "description": "Liveness and readiness probes" }, { "name": "auth", "description": "Sign-up, sign-in, sessions and 2FA" }, { "name": "organizations", "description": "Organizations, members and invites" }, { "name": "verify", "description": "Verify one address or a list of them" }, { "name": "discovery", "description": "Domain search, email finder and company profiles" }, { "name": "leads", "description": "Saved contacts and lists" }, { "name": "credits", "description": "Balance, ledger and usage" }, { "name": "billing", "description": "Plans, checkout and invoices" }, { "name": "api-keys", "description": "Programmatic access credentials" }, { "name": "webhooks", "description": "Event subscriptions and deliveries" }, { "name": "compliance", "description": "Suppression and data-subject requests" } ], "externalDocs": { "description": "Documentation", "url": "https://verifyinbox.tech/docs" } }