> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Postman collection

> Import the official Perkstar collection and production environment for repeatable API testing.

The official Postman collection is generated from the same OpenAPI contract as
this reference. It contains all 25 public v1 operations, example bodies,
inherited bearer authentication, request tracing checks, and automatic ID
capture for multi-step testing.

<CardGroup cols={2}>
  <Card title="Download collection" icon="download" href="https://dashboard.perkstar.co.uk/developer-downloads/perkstar-public-api.postman_collection.json">
    Requests grouped by customers, enrolments, transactions, cards, webhooks,
    locations, pushes, and marketplace operations.
  </Card>

  <Card title="Download environment" icon="sliders" href="https://dashboard.perkstar.co.uk/developer-downloads/perkstar-production.postman_environment.json">
    Production base URL and safe placeholder variables. It contains no live
    credential.
  </Card>
</CardGroup>

## Import and connect

<Steps>
  <Step title="Import both files">
    In Postman, choose **Import**, select the collection and environment JSON
    files, then select **Perkstar Production** in the environment menu.
  </Step>

  <Step title="Add a test key">
    Create a read-only test key in **Dashboard → Settings → API keys**. Replace
    the `api_key` environment value with that key and mark the value as secret.
  </Step>

  <Step title="Run the connection check">
    Open **Marketplace → Auth check + org context** and send the request. A
    successful response identifies the connected business and available cards.
  </Step>

  <Step title="Run a read-only folder">
    Run the **Cards** folder first. Collection tests verify the API version,
    request ID, and absence of a server error on every response.
  </Step>
</Steps>

## Write requests

POST requests use Postman's `{{$guid}}` dynamic variable for a fresh
`Idempotency-Key`. Replace it with a stable business reference when testing a
job that may be replayed from another process. For a manual retry, keep the
resolved key from the first request instead of generating another one.

<Warning>
  The collection includes write and delete requests. A read-only key keeps those
  requests safely blocked. Add only the scopes needed for the operation you are
  deliberately testing, and use a test key before switching to live.
</Warning>

## Keep it current

The collection and environment are regenerated whenever the canonical API
contract changes. CI rejects a release if the checked-in files are stale or if
their method and path coverage differs from the OpenAPI reference.


## Related topics

- [Quickstart](/quickstart.md)
- [Changelog](/changelog.md)
- [Pagination](/fundamentals/pagination.md)
- [Perkstar developer platform](/index.md)