API reference

Everything you can do on the website, you can do with the API. The same operations are also available to AI assistants through MCP.

Basics#

• Base URL: https://api.getverifiedinbox.com. All endpoints are under /v1.
• Format: JSON bodies (Content-Type: application/json), UTF-8. Timestamps are RFC 3339 (UTC). Money is in integer cents (USD).
• Versioning: v1 only changes in backward-compatible ways (new fields may appear).
• Pagination: list responses look like { "data": [...], "next_cursor": null }.

Authentication#

You can send a guest token together with an account credential (guest token in VI-Guest-Token): that's how anonymous drafts are claimed. OAuth callers can add VI-Environment: live|test and VI-Organization: <id>. API keys are bound to one organization and environment.

Scopes: applications:read, applications:write, billing:write, certificates:write, support:write.

Conventions#

• Errors return { "error": { "code", "message", "details"?, "next_action"? } }. The message is plain English. Common codes: invalid_request (400), unauthenticated (401), payment_required (402), forbidden/insufficient_scope (403), not_found (404), version_conflict/conflict (409), unprocessable/blocked_provider (422), rate_limited (429, with Retry-After), upstream_unavailable (503). Resources you can't access return 404, never 403.
• Idempotency: checkout and certificate operations require an Idempotency-Key header (up to 255 characters); starting an application accepts one. Same key and body → the original response is replayed; same key with a different body → 409. The x-idempotency field of each operation in the OpenAPI document says which.
• Concurrency: applications have a version. Send If-Match: "<version>" on user-driven changes to avoid overwriting someone else's edit (409 version_conflict returns the current application).
• Next actions: application responses include next_actions, each with a title, the step, whether it needs sign-in or payment, and the matching API call and MCP tool.

OpenAPI#

The complete, machine-readable contract is an OpenAPI 3.1 document:

• https://getverifiedinbox.com/openapi.json (also served by the API at https://api.getverifiedinbox.com/openapi.json)

Import it into Postman, Insomnia or an SDK generator, or hand it to an AI assistant. Each operation lists who may call it (x-access), whether it needs an Idempotency-Key (x-idempotency), and the MCP tool that does the same thing (x-mcp-tools). The tables below are generated from that document, so they always match the live API. More: OpenAPI schema.

Endpoints#

Meta#

Service metadata, health and this contract.

Checks#

Free, repeatable public checks of any domain.

Glossary#

Plain-English definitions of every term we use.

Guest sessions#

Anonymous credentials and resume links.

Applications#

The server-side state of one domain's journey.

Email health#

SPF, DKIM, DMARC and BIMI for an application.

Logo#

Logo intake, SVG Tiny P/S conversion and approval.

Trademark#

USPTO trademark search and verification.

Eligibility#

VMC / CMC / not-yet-eligible outcome and price estimate.

Checkout#

Stripe hosted checkout (agents create links; people pay).

Business#

Legal company verification.

DNS#

The DNS records to add, with live status.

Test messages#

Authentication results on a real email.

Certificate#

Certificate order, status, reissue, renewal and revocation.

Go live#

BIMI publication and display confirmation.

Account#

Profile, organizations, environment, API keys, orders.

Support#

Contact a human, feedback and feature requests.

Hosting#

Public logo and certificate files referenced by BIMI records.

MCP#

Model Context Protocol endpoint and OAuth discovery.

Test mode#

Sandbox helpers (no real payments).

Example#

# Check a domain
curl -s https://api.getverifiedinbox.com/v1/checks/domain \
  -H 'Content-Type: application/json' \
  -d '{"domain":"acme.com"}'

# Start an application (save the guest_token from the response)
curl -s https://api.getverifiedinbox.com/v1/applications \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: start-acme-1' \
  -d '{"domain":"acme.com"}'

# Read it later
curl -s https://api.getverifiedinbox.com/v1/applications/APPLICATION_ID \
  -H 'VI-Guest-Token: vi_guest_…'

Rate limits#

Anonymous requests are limited per IP address and per guest token, and expensive work has daily budgets. When you hit a limit you get 429 with Retry-After (seconds). Poll background work gently.