# API reference

> The VerifiedInbox REST API (v1). Every step of the process is an API call; free steps work without an account.

Everything you can do on the website, you can do with the API. The same operations are also available to AI assistants through [MCP](https://getverifiedinbox.com/docs/mcp.md).

## 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

| Credential | How to send it | For |
|---|---|---|
| None | — | Public checks |
| Guest token | `VI-Guest-Token: vi_guest_…` or `Authorization: Bearer vi_guest_…` | Continuing an anonymous application |
| API key | `Authorization: Bearer vi_live_…` or `vi_test_…` | Servers, scripts, AI agents ([API keys](https://getverifiedinbox.com/docs/glossary.md#api-key)) |
| OAuth token | `Authorization: Bearer <token>` (WorkOS) | MCP clients signed in as a person |

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`](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](https://getverifiedinbox.com/docs/openapi.md).

## Endpoints

<!-- BEGIN GENERATED: endpoints (make contract) -->

### Meta

Service metadata, health and this contract.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /health` | Liveness check | Public — no credentials needed | — |
| `GET /openapi.json` | This OpenAPI document | Public — no credentials needed | — |
| `GET /ready` | Readiness check | Public — no credentials needed | — |
| `GET /v1/meta` | Pricing, steps and live/mocked integrations | Public — no credentials needed | `get_started` |

### Checks

Free, repeatable public checks of any domain.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `POST /v1/checks/domain` | Quick domain eligibility check | Public — no credentials needed | `check_domain` |
| `POST /v1/checks/email-auth` | Full SPF/DKIM/DMARC/BIMI inspection | Public — no credentials needed | `check_email_security` |
| `GET /v1/providers/blocked` | Shared mailbox domains that can't be used | Public — no credentials needed | — |

### Glossary

Plain-English definitions of every term we use.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/glossary` | All glossary terms | Public — no credentials needed | — |
| `GET /v1/glossary/{term}` | One glossary term | Public — no credentials needed | `explain_term` |

### Guest sessions

Anonymous credentials and resume links.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `POST /v1/guest-sessions` | Create a guest credential | Public — no credentials needed | — |
| `DELETE /v1/guest-sessions/current` | Revoke the current guest session | Free — guest or account | — |
| `POST /v1/resume` | Exchange a one-time resume token | Public — no credentials needed | — |

### Applications

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

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/applications` | List my verifications | Free — guest or account | `list_applications`, `get_account` |
| `POST /v1/applications` | Start (or resume) a verification | Public — no credentials needed | `start_application` |
| `GET /v1/applications/{application_id}` | Get a verification | Free — guest or account | `get_application` |
| `PATCH /v1/applications/{application_id}` | Choose product / contact email | Free — guest or account | — |
| `POST /v1/applications/{application_id}/archive` | Archive (unpaid only) | Free — guest or account | — |
| `POST /v1/applications/{application_id}/claim` | Move a guest draft into the account | Account required | `claim_application` |
| `GET /v1/applications/{application_id}/events` | Timeline of the verification | Free — guest or account | — |
| `GET /v1/applications/{application_id}/next-steps` | Current step and next actions | Free — guest or account | `get_application` |
| `POST /v1/applications/{application_id}/refresh` | Re-run checks now | Free — guest or account | — |
| `POST /v1/applications/{application_id}/resume-links` | One-time link to continue in a browser | Free — guest or account | `create_resume_link` |
| `POST /v1/applications/{application_id}/steps/{step}/complete` | Complete a wizard step and move on | Free — guest or account | `complete_step` |

### Email health

SPF, DKIM, DMARC and BIMI for an application.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `POST /v1/applications/{application_id}/dkim-selectors` | Verify DKIM selectors you supply | Free — guest or account | `verify_dkim_selectors` |
| `GET /v1/applications/{application_id}/email-health` | Latest email-security report + DMARC rollout plan | Free — guest or account | — |
| `POST /v1/applications/{application_id}/email-health/check` | Re-check email security now | Free — guest or account | `recheck_email_security` |
| `PUT /v1/applications/{application_id}/email-usage` | How email is used on the domain | Free — guest or account | `set_email_usage` |

### Logo

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

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/applications/{application_id}/logo` | Logo status, analysis and changes | Free — guest or account | `get_logo_status` |
| `PUT /v1/applications/{application_id}/logo` | Submit the logo | Free — guest or account | `submit_logo` |
| `GET /v1/applications/{application_id}/logo-candidates` | Logos found on the website | Free — guest or account | `get_logo_status` |
| `POST /v1/applications/{application_id}/logo/approve` | Approve the reviewed inbox-ready logo | Paid plan required | `approve_logo` |
| `GET /v1/applications/{application_id}/logo/converted.svg` | Inbox-ready SVG Tiny P/S file | Free — guest or account | — |
| `GET /v1/applications/{application_id}/logo/original.svg` | Original logo file | Free — guest or account | — |
| `GET /v1/applications/{application_id}/logo/preview.png` | Rendered PNG preview | Free — guest or account | — |

### Trademark

USPTO trademark search and verification.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/applications/{application_id}/trademark` | Trademark result | Free — guest or account | `get_trademark_status` |
| `POST /v1/applications/{application_id}/trademark/claim` | Verify a specific USPTO number | Free — guest or account | `search_trademark` |
| `POST /v1/applications/{application_id}/trademark/search` | (Re)start the USPTO search | Free — guest or account | `search_trademark` |

### Eligibility

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

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/applications/{application_id}/eligibility` | VMC / CMC / not-yet-eligible with evidence | Free — guest or account | `get_eligibility` |
| `POST /v1/applications/{application_id}/eligibility/watch` | Email me when this domain qualifies | Free — guest or account | `watch_eligibility` |
| `GET /v1/applications/{application_id}/estimate` | Itemized yearly price | Free — guest or account | `get_estimate` |

### Checkout

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

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `POST /v1/applications/{application_id}/checkout` | Create a Stripe checkout link | Account required | `create_checkout` |

### Business

Legal company verification.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/applications/{application_id}/business` | Company verification status | Free — guest or account | `get_business_status` |
| `PUT /v1/applications/{application_id}/business` | Submit legal company details | Paid plan required | `submit_business_details` |

### DNS

The DNS records to add, with live status.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/applications/{application_id}/dns` | Every DNS record to add, with live status | Paid plan required | `get_dns_records` |
| `POST /v1/applications/{application_id}/dns/verify` | Re-check DNS now | Paid plan required | `verify_dns` |

### Test messages

Authentication results on a real email.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `POST /v1/applications/{application_id}/test-messages` | Get an address to send a real test email to | Account required | `create_test_message` |
| `GET /v1/applications/{application_id}/test-messages/{test_message_id}` | Authentication results of the test email | Free — guest or account | `get_test_message_result` |

### Certificate

Certificate order, status, reissue, renewal and revocation.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/applications/{application_id}/certificate` | Certificate status, prerequisites, final check and history | Free — guest or account | `get_certificate` |
| `POST /v1/applications/{application_id}/certificate/check` | Re-check everything the issuer will verify | Paid plan required | `run_final_check` |
| `POST /v1/applications/{application_id}/certificate/order` | Submit the order (normally automatic) | Paid plan required | `order_certificate` |
| `POST /v1/applications/{application_id}/certificate/reissue` | Reissue the certificate | Paid plan required | `reissue_certificate` |
| `POST /v1/applications/{application_id}/certificate/renew` | Renew early | Paid plan required | `renew_certificate` |
| `POST /v1/applications/{application_id}/certificate/revoke` | Revoke permanently | Paid plan required | `revoke_certificate` |

### Go live

BIMI publication and display confirmation.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/applications/{application_id}/go-live` | BIMI publication, test email, display, monitoring, renewal | Free — guest or account | — |
| `POST /v1/applications/{application_id}/inbox-display` | Record that the logo was seen in a mailbox | Paid plan required | `confirm_inbox_display` |

### Account

Profile, organizations, environment, API keys, orders.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /v1/api-keys` | API keys | Account required | — |
| `POST /v1/api-keys` | Create an API key (web session) | Account required | — |
| `DELETE /v1/api-keys/{api_key_id}` | Revoke an API key | Account required | — |
| `POST /v1/billing/portal` | Stripe billing portal link | Account required | — |
| `GET /v1/me` | Who am I (works anonymously too) | Public — no credentials needed | `get_account` |
| `POST /v1/me/environment` | Switch live/test mode (web session) | Account required | — |
| `POST /v1/me/organization` | Switch organization (web session) | Account required | — |
| `GET /v1/notifications` | Notification log | Account required | — |
| `GET /v1/orders` | Orders and payments | Account required | `get_account`, `list_orders` |
| `GET /v1/orders/{order_id}` | One order | Account required | `list_orders` |
| `GET /v1/organizations` | My organizations | Account required | — |
| `POST /v1/organizations` | Create an organization | Account required | — |
| `GET /v1/organizations/{organization_id}` | One organization | Account required | — |
| `PATCH /v1/organizations/{organization_id}` | Rename an organization | Account required | — |
| `GET /v1/organizations/{organization_id}/members` | Organization members | Account required | — |

### Support

Contact a human, feedback and feature requests.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `POST /v1/support` | Contact a human, feedback, feature request, partnership | Public — no credentials needed | `contact_support`, `send_feedback` |

### Hosting

Public logo and certificate files referenced by BIMI records.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /bimi/test/{domain}/{file}` | Hosted BIMI assets (test mode) | Public — no credentials needed | — |
| `GET /bimi/{domain}/{file}` | Hosted BIMI logo / certificate | Public — no credentials needed | — |

### MCP

Model Context Protocol endpoint and OAuth discovery.

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `GET /.well-known/oauth-protected-resource` | OAuth protected-resource metadata (RFC 9728) | Public — no credentials needed | — |
| `GET /.well-known/oauth-protected-resource/mcp` | OAuth protected-resource metadata for /mcp | Public — no credentials needed | — |
| `POST /mcp` | MCP endpoint (Streamable HTTP, JSON responses) | Public — no credentials needed | — |

### Test mode

Sandbox helpers (no real payments).

| Method & path | Summary | Access | MCP tool |
|---|---|---|---|
| `POST /v1/dev/mock-checkout/{order_id}/complete` | Simulate payment of a mock checkout | Account required | — |
<!-- END GENERATED: endpoints -->

## Example

```bash
# 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.