Postman & MCP

The VerityPay API is published as a public Postman workspace with a maintained OpenAPI 3.1 specification and a ready-to-import collection. You can use it three ways:

1. Click-to-import the collection into your own Postman workspace.
2. Fork & subscribe so updates from VerityPay flow into your fork.
3. Connect an AI agent through Postman's MCP server.

The artifacts

The collection UID is 27372647-139029f1-237f-4af3-af82-6c281da6bb6d — you'll plug this into clients and the MCP server.

Import the collection

Option 1 — One-click "Run in Postman"

Click the link above; Postman will prompt you to choose a workspace and import. This brings down a snapshot — it does not subscribe you to updates.

Option 2 — Fork (recommended)

Forking lets you receive updates from the source collection while keeping local edits.

1. Open the VerityPay API v1 collection.
2. Click Fork → choose your destination workspace.
3. Toggle Watch this collection to be notified when new endpoints land.

When upstream changes ship, Postman shows a Pull changes prompt on your fork.

Option 3 — Programmatic import

Use the workspace UID and collection UID with any tool that speaks the Postman API:

curl https://api.getpostman.com/collections/27372647-139029f1-237f-4af3-af82-6c281da6bb6d \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -o veritypay-collection.json

The same UID feeds Newman:

newman run https://api.getpostman.com/collections/27372647-139029f1-237f-4af3-af82-6c281da6bb6d?apikey=$POSTMAN_API_KEY \
  --env-var "baseUrl=https://staging.app.veritypay.com/api/v1" \
  --env-var "token=$VERITYPAY_TOKEN"

Setting up the Postman environment

Once imported, define a Postman environment with two variables:

The collection's bearer-auth is wired to {{token}} and every request uses {{baseUrl}} so the same collection works against both environments.

Never commit a populated environment to git. Postman exports include the variable values in plaintext. Use Postman's Vault for tokens, or keep environments local.

Postman MCP server

Postman's MCP server lets AI agents (Claude, Cursor, Windsurf, etc.) plan and execute requests against your APIs without you wiring per-endpoint tools.

What it gives an agent

Once configured, any MCP-aware agent can:

• Discover the VerityPay API by reading the OpenAPI spec.
• Reason about request/response shapes from the spec — no manual schema work.
• Send live requests through your Postman environment (with the agent's secrets/token, not yours-as-a-user).
• Mock endpoints via Postman mock servers if you want to integrate before the real API is wired up.

Connect Claude Code

In ~/.claude.json (or .mcp.json in your project), add:

{
  "mcpServers": {
    "postman": {
      "type": "http",
      "url": "https://mcp.postman.com/mcp",
      "headers": {
        "X-Api-Key": "PMAK_••••••••••••••••••••"
      }
    }
  }
}

Then in any prompt:

"Using the Postman MCP, list all requests in the VerityPay API v1 collection (UID 27372647-139029f1-237f-4af3-af82-6c281da6bb6d) and create a contact for Jane Doe at +15551234567 in the staging environment."

Connect Claude Desktop / Cursor / Windsurf

Each editor has its own MCP config file but the schema is identical. Get a Postman API key (Settings → API Keys → Generate API Key) and paste it into the X-Api-Key header.

The MCP exposes Postman-level tools (getCollections, createCollectionRequest, etc.) — pin the collection by mentioning its UID in your prompt or storing it as agent context.

MCP best practices

• One Postman API key per workload. Don't share your personal key with shared agents.
• Scope the agent to a workspace in your prompts. "In workspace d0e84434-5495-47f8-8595-0b1a69efcdc2, …" prevents the agent from mutating unrelated collections.
• Read-only by default. Most integrations only need get tools — explicitly list the create/update tools you want available.
• Treat agent-generated requests as code review material. An LLM happily writes 30 contacts in a loop; before you run an agent's plan, eyeball the dry-run.
• Use the staging environment for anything an agent drafts. Promote to production after a human confirms the result.

Best practices for documentation-led development

If your team is consuming this API at scale, the Postman workspace is also a great backbone for your own documentation:

1. Sync the spec to your repo. Use the Postman API to pull 27372647-5210cc3a-5ff8-4836-9902-2fbb13db07cb into a specs/openapi.yaml file. Treat changes as PRs.
2. Generate clients from the spec. Tools like openapi-generator produce typed clients in 50+ languages from the same OpenAPI document.
3. Run contract tests on your fork. Use Newman (newman run …) in CI. If VerityPay changes a response shape, your CI fails before your customers do.
4. Keep a changelog alongside your fork. When you pull upstream, note in your fork's README.md what changed, and any code adaptations you needed.
5. Use Postman mocks for dev environments. Don't burn rate-limit headroom against staging while three engineers fiddle with form bodies.
6. Pin the spec version. Each spec revision in Postman has an immutable URL — depend on a specific version in CI rather than latest so a documentation update doesn't accidentally fail your pipeline.

Reporting issues with the spec

The OpenAPI spec is the source of truth — if a request shape, status code, or error envelope doesn't match what the API actually returns, that's a bug. Report it to api-support@veritypay.com with the request_id from the unexpected response and a link to the offending request in your Postman fork.