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

# Run the API in Postman

> Import the official Perkstar collection and environment for repeatable, end-to-end API testing.

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

<Note>
  This collection is a testing tool, not a second source of API truth. Guides
  explain behaviour and the OpenAPI reference defines the contract; the Postman
  files make that contract quick to exercise.
</Note>

<CardGroup cols={2}>
  <Card title="Import collection URL" icon="download" href="https://dashboard.perkstar.co.uk/developer-downloads/perkstar-public-api.postman_collection.json">
    In Postman choose **Import → Link** and paste this URL. Requests are grouped
    by customers, enrolments, transactions, cards, webhooks, locations, pushes,
    and marketplace operations.
  </Card>

  <Card title="Import 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 the collection">
    In Postman, choose **Import → Link** and paste:

    ```text theme={null}
    https://dashboard.perkstar.co.uk/developer-downloads/perkstar-public-api.postman_collection.json
    ```

    Import the environment file from the card above, 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.

## What to run before launch

<AccordionGroup>
  <Accordion title="Authentication smoke test">
    Run **Marketplace → Auth check + org context**. Confirm the response names
    the intended business, reports the expected key mode, and lists the cards
    your integration expects.
  </Accordion>

  <Accordion title="Read-path contract test">
    Run the Cards, Locations, Customers, and Enrolments folders with a read-only
    test key. Collection tests verify request IDs and reject unexpected server
    errors.
  </Accordion>

  <Accordion title="Write and retry test">
    Use a test key and an existing enrolment. Send the same write twice with the
    same resolved `Idempotency-Key`; the second response must replay safely
    rather than apply loyalty twice.
  </Accordion>

  <Accordion title="Webhook receiver test">
    Create a test endpoint, store the signing secret, send `webhook.test`, and
    verify the raw request body before parsing it. Then compare your handler
    against the [event catalogue](/reference/webhook-events).
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.