Postman API documentation: public workspace, live sandbox

What Postman is for when you work with an API

Postman is an HTTP client with a memory. A request is one call with its method, URL, headers and body; a collection is a folder of requests that share variables and auth; an environment is a set of variable values (host, key) you can switch without editing a request. Add a Tests script and a collection becomes a runnable check; add descriptions and saved examples and it becomes documentation Postman can publish.

For an API like this one it answers three questions quickly: *does my key work?*, *what does this endpoint actually return?*, and *what does the request look like in my language?* — the code snippet panel translates any request into curl, Python, JavaScript and more.

Import the OffenderSearch collection and environment

Two files, both generated from the published OpenAPI document so they cannot drift from the API:

• offendersearch.postman_collection.json — Every public endpoint in eight folders — Sex Offender Search, Criminal Records, Monitoring, Map API, Clearances, FCRA Partner API, FCRA consumer portal, Account & support — with request bodies taken from the sandbox's own scenarios.
• sandbox.postman_environment.json — base_url set to the sandbox host and api_key as a secret variable you fill in.

1. Import both files. Postman → Import → drop the two files (or paste their URLs). The collection lands in your workspace; the environment appears in the environment selector.
2. Create a test key. Dashboard → API keys → Create test key. It begins os_test_, works only on the sandbox and is never billed. 25 free live calls come with the account too, but the sandbox is where you learn.
3. Set api_key in the environment. Select the OffenderSearch sandbox environment, open it, paste the key into api_key (it is a secret-type variable, masked in the UI and excluded from exports).
4. Send. Open Sex Offender Search → Synchronous search and press Send. The body is already a name the sandbox matches.

Postman environment variables: base_url and api_key

{
  "name": "OffenderSearch sandbox",
  "values": [
    { "key": "base_url", "value": "https://sandbox.offendersearch.app", "type": "default", "enabled": true },
    { "key": "api_key",  "value": "os_test_...",                         "type": "secret",  "enabled": true }
  ]
}

Duplicate the environment, rename it production, change the two values, and switching environments switches hosts with no request edited. Keep api_key a *secret* variable so it never lands in an exported file or a shared workspace — the lifecycle of the key itself is on the API token example page.

Send a sandbox request and read the answer

The sandbox answers fixed names with fixed outcomes, so a request is also a known-good check. The collection's first search uses the name that returns one date-of-birth-verified match:

POST {{base_url}}/v1/search
X-API-Key: {{api_key}}
Content-Type: application/json

{
  "query": { "firstName": "Exact", "lastName": "Match", "dob": "1980-01-01" }
}

{
  "status": "complete",
  "counts": { "records": 1, "recordsReturned": 1, "sourcesQueried": 58, "sourcesComplete": 58, "sourcesIncomplete": 0 },
  "records": [
    {
      "matchState": "dob_match",
      "matchedName": { "value": "Exact Match", "type": "legal" },
      "matchConfidence": 0.9,
      "registrationState": "OH"
    }
  ],
  "sandbox": true
}

Change the last name to anything not on the sandbox list and the same request returns status: complete with zero records — the other branch every integration must handle. Send Felony Record with dob 1975-06-15 to Criminal Records → Search criminal records for one felony court case, and Monitoring → Create a monitor for a 201 with an immediate alert. Every scenario and its expected fields are listed on the sandbox page and in the collection's request descriptions.

Postman tests: turn a request into a check

The Tests tab runs JavaScript after a response arrives. Because the sandbox is deterministic, a test can assert exact values, which makes the collection a smoke test of your key, your network and the API in one click of the Collection Runner.

// Tests tab — runs after the response arrives
pm.test("200 OK", () => pm.response.to.have.status(200));

const body = pm.response.json();
pm.test("the answer is complete", () => pm.expect(body.status).to.eql("complete"));
pm.test("one DOB-verified match", () => {
  pm.expect(body.counts.records).to.eql(1);
  pm.expect(body.records[0].matchState).to.eql("dob_match");
});

// Hand the id to the next request in the collection
pm.collectionVariables.set("searchId", body.searchId);

Chaining is the second use: store an id from one response in a collection variable and the next request reads it — the search id into the verification report request, the monitor id into its alerts request. The Runner executes the folder in order with the variables flowing through.

API documentation in Postman: how a collection becomes docs

Postman renders a collection as documentation: the collection description becomes the overview, each folder description a section, each request's description its page, with the method, URL, headers, body and saved example responses shown beside it, and the code snippet in the reader's chosen language. Publishing makes that page public at a Postman URL; a public workspace adds forking and version history.

1. Describe at every level. Collection, folder and request descriptions are Markdown. The generated collection carries each endpoint's summary and description from the OpenAPI document; add your own notes on top.
2. Save example responses. Send a request, then Save as example. Documentation with a real response is documentation someone can trust.
3. Keep secrets out. Use {{api_key}} everywhere and keep the real value in a secret environment variable. Published docs show the placeholder.
4. Publish. View documentation → Publish, or make the workspace public. Re-publishing after an import keeps the URL.

What Postman documentation is good at: one request, one response, one snippet per language, always current with the collection. What it is not: concept pages, guides and the error contract — those live in a portal like this one, which is why the collection links back to the docs on every folder.

Create a collection from an OpenAPI document

You do not have to start from ours. Import → paste a URL and give Postman /openapi.yaml: it generates a collection with every path, parameter and schema-derived body. That is how the published collection is built, with two additions a plain import does not make — the request bodies are the sandbox's real scenario names rather than schema placeholders, and the header, variables and folder notes are set for the sandbox-first workflow. The generator is a small script; re-running it after an API change regenerates the files, and a test fails when the committed files are stale.

• After importing any OpenAPI document, set the collection's Authorization once (API key, header X-API-Key, value {{api_key}}) and let requests inherit it.
• Replace schema placeholder bodies with values the API actually accepts; a "string" where a date goes teaches nothing.
• Name the environment after the host, not the project — sandbox, production — so the selector reads as a switch.

Postman vs curl vs an SDK

The same request, three ways. Postman is for exploring and documenting; curl is for scripts and bug reports; an SDK is for the code you ship.

curl -X POST https://sandbox.offendersearch.app/v1/search \
  -H "X-API-Key: $OFFENDERSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": {"firstName": "Exact", "lastName": "Match", "dob": "1980-01-01"}}'

Postman FAQ

How do I use the postman api documentation for OffenderSearch?

Import the collection and environment files from this page, set api_key to a test key, and send any request. Each request's description is the endpoint's documentation; the full docs are at /docs.

How do I create api documentation with postman?

Write Markdown descriptions on the collection, folders and requests, save example responses, keep secrets in environment variables, then View documentation → Publish. Postman renders a page per request with the snippet in the reader's language.

Can I generate a postman collection from an api?

From its OpenAPI document, yes: Import → URL → the openapi.yaml. Every path becomes a request. Then fix the bodies and set collection-level auth.

Is there a public postman workspace for this API?

The collection and environment are published as files here. When a public workspace on Postman's API network is live, its link is added to this page and to /postman.

Why does my request return 401 in Postman?

The environment is not selected, api_key is empty, or the key's prefix does not match base_url — os_test_ keys work only on the sandbox host, os_live_ only on the live host. Check the environment selector in the top right first.

Does sending requests from Postman cost anything?

Against the sandbox, never. Against production with a live key, each call is billed at the published rate ($0.15 a call) after the account's 25 free calls.

What this page does not cover

• Postman's team features — workspaces, roles, monitors, mock servers, the Postman API itself. Its own documentation covers those.
• Newman and CLI runs of the collection in CI. The collection works with them unchanged; the setup is Postman's to document.
• The endpoints' semantics. The collection links each folder to the product documentation: sex offender, criminal, monitoring, map, FCRA.

Related

• Postman collection and sandbox environment (download page)
• Public API for testing: the sandbox
• The sandbox's fixed test names and outcomes
• API documentation example: what good docs look like
• API token example: create, scope, rotate and revoke a key
• RESTful API example: one request, one response
• API errors: designing codes a client can act on
• The OpenAPI document
• Python and Node SDKs
• Background check API
• Criminal records API
• All learning guides