Skip to main content

​
OpenAPI Specification

Use the OpenAPI spec when generating SDKs, configuring coding agents, or validating integrations against the current public API contract.

Download OpenAPI JSON

Machine-readable OpenAPI 3.1 reference for available-now Email Validation, Premium Catch-All Recovery, account credit balance, and health probes.

​
Response Correlation

Every documented HTTP response includes an opaque X-Request-ID header. Keep the ID from the terminal response and include it in support reports. If retries end in a network-only failure, there is no server request ID for that final attempt. The identifier is support metadata only. It never changes validation evidence, credits, suppression, or sending decisions. Browser integrations from allowed origins can read the header through CORS, and the official clients expose it on their typed or structured HTTP errors.

​
Operation Authorization

Every protected operation publishes two GTMAPIs OpenAPI extensions:
  • x-gtmapis-required-scope gives the exact API-key scope required by the operation.
  • x-gtmapis-scope-mode is compatible for validation-era routes that retain legacy-key access, or exact for permissions such as outcome import and reporting.
Use these fields when an SDK, agent, or integration creates a least-privilege key. Public health operations do not include either extension.

​
Scope

The spec documents the available-now public API surface:
  • POST https://api.gtmapis.com/v1/validate
  • POST https://api.gtmapis.com/v1/validate/bulk
  • POST https://api.gtmapis.com/v1/validate/batch
  • POST https://api.gtmapis.com/v1/csv/prepare-upload
  • POST https://api.gtmapis.com/v1/csv/start-processing
  • GET https://api.gtmapis.com/v1/csv/jobs
  • GET https://api.gtmapis.com/v1/csv/jobs/{id}
  • GET https://api.gtmapis.com/v1/csv/jobs/{id}/download
  • POST https://api.gtmapis.com/v1/csv/jobs/{id}/recover-catchalls
  • GET https://api.gtmapis.com/v1/csv/jobs/{id}/recovery
  • GET https://api.gtmapis.com/v1/credits
  • POST https://api.gtmapis.com/v1/outcomes/email/import
  • GET https://api.gtmapis.com/v1/outcomes/email/report
  • GET https://api.gtmapis.com/v1/outcomes/email/connectors/emailbison
  • POST https://api.gtmapis.com/v1/outcomes/email/connectors/emailbison
  • DELETE https://api.gtmapis.com/v1/outcomes/email/connectors/emailbison
  • GET https://api.gtmapis.com/.well-known/jwks.json
  • GET https://api.gtmapis.com/health
  • GET https://api.gtmapis.com/ready
  • GET https://api.gtmapis.com/live
The public API scope is Email Validation and Premium Catch-All Recovery.

​
Source of Truth

The canonical public API host is:
All public examples should combine that host with public paths such as /v1/validate, not website-internal Next.js route paths such as /api/v1/validate.