# Import the Spaw OpenAPI document into Postman or a generator

An OpenAPI 3.1 document with 17 operations, examples and error schemas lives at /openapi.json: import it into Postman, Insomnia or Bruno, or generate a client.

Updated: 2026-09-03

Every Spaw endpoint is described in one OpenAPI 3.1 document, which is also the source the reference pages are rendered from, so the two can never disagree. It is served as JSON at `https://spaw.co/openapi.json` and as YAML at `https://spaw.co/openapi.yaml`, with no authentication. If your tool understands OpenAPI, it understands Spaw.

## What the document contains

The 17 operations cover single and batch verification, the browser endpoint for publishable keys, domain intelligence, the four bulk-job calls, the three suppression-list calls, delivery feedback, the accuracy summary, the provider webhook target, the account endpoint, and the phone and IP endpoints. Each operation carries a request example, a response example, and the named error responses it can return. Three vendor extensions add what a generated client cannot infer: `x-spaw-auth` says whether the operation takes a bearer key, a publishable key or a feedback key, `x-spaw-billing` states in one sentence what the operation costs, and `x-spaw-errors` lists the stable error codes.

The `EmailResult` schema documents all 27 fields of a verification with their meaning, and the `ErrorEnvelope` schema is the shape of every failure: `{ "success": false, "error": { "code", "message", "request_id" } }`, with `error.errors` keyed by field on a validation failure.

## Import into an API client

1. Create a secret key on the API keys page.
2. In Postman, choose Import and paste `https://spaw.co/openapi.yaml`; Postman builds a collection with one request per operation. Insomnia and Bruno both import an OpenAPI URL or file the same way.
3. Set the collection's authorization to bearer token and paste the key. The document declares the `bearerAuth` scheme on every operation, so the tools apply it automatically.
4. Send the first request against a test address, which costs nothing:

```json
POST https://spaw.co/api/v1/email
{ "email": "deliverable@spaw.test" }
```

The six fixed addresses on `spaw.test` answer canonical verdicts, are never billed, and never appear in your history, so a shared collection can be exercised freely.

## Generate a client

Any generator that reads OpenAPI 3.1 works; recent releases of openapi-generator do. For example:

```bash
openapi-generator-cli generate \
  -i https://spaw.co/openapi.yaml \
  -g typescript-fetch \
  -o ./spaw-client
```

Before generating, check whether an official client already exists for your language: Spaw ships hand-written Python, Node.js and PHP clients built from this same document, with the error classes already mapped to the API's codes. A generated client is the right choice for Go, Ruby, Java, C# and everything else.

## Use it with AI tools

The document is also the fastest way to teach a coding assistant the API. Point it at `https://spaw.co/openapi.yaml`, or at `https://spaw.co/llms-full.txt`, which concatenates every documentation page, the endpoint reference and the verdict reasons into one Markdown file. Each endpoint page under `/docs/api/{operationId}` has a Markdown twin at the same URL with `.md` appended.

## What to do with the verdict

Whatever the tool, the answer is the same 27-field object. Branch on `deliverable`: keep `deliverable`, drop `undeliverable`, and route `risky` by `reason`. The `sources` array names the dataset and version behind every answer, which is what to quote when a verdict surprises you.

## Cost

Importing or generating costs nothing. Lookups follow the usual rules: one credit per fresh deliverable or risky verdict, and nothing for undeliverable verdicts, invalid input, repeats within seven days or the test addresses. Every account gets 10 free lookups a month, and `GET /api/v1/account` reads the live balance for free.

Reference: https://spaw.co/integrations/openapi