API quickstart

PocketPass is API-first: everything the dashboard does, the API does. This guide gets you from nothing to a real pass in a few minutes.

The full interactive reference, with every parameter and response, lives at the API reference. This article is the orientation.

Base URL

https://api-prod.getpocketpass.com

All endpoints are under /api/v1.

Step 1 - Create an API key

Open Settings → API keys, create a key and give it a name that says where it'll be used - "Booking system", "Staging".

The key is shown once. Copy it into your secret store there and then. If you lose it, revoke it and create another. See API keys and authentication.

Step 2 - Check it works

Every request carries the key as a bearer token.

curl https://api-prod.getpocketpass.com/api/v1/pass-templates \
  -H "Authorization: Bearer pk_live_your_key_here"

You'll get back your templates. If you get a 401, the key is wrong or revoked; if 403, check the account isn't suspended.

Note the id of the template you want to issue from - you'll need it next.

Step 3 - Create a pass

The template is passed as a query parameter, and the field values go in the body.

curl -X POST "https://api-prod.getpocketpass.com/api/v1/passes?passTemplate=TEMPLATE_ID&extId=member-10248" \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "passContent": {
      "memberName": { "value": "Jane Doe" },
      "tier": { "value": "Gold" }
    },
    "groupTags": ["vip", "london"]
  }'

The keys inside passContent are the field ids from your template, not the labels. You can see them in the template builder under Show advanced, or in the response from GET /api/v1/pass-templates/{id}.

Step 4 - Send the customer their pass

The response includes the pass id. The install page is:

https://getpocketpass.com/p/{passId}

Send that link, or render its QR code. That's the whole customer journey - see How customers add a pass.

Step 5 - Update it later

Because you set extId on create, you can address the pass by your own reference rather than storing ours:

curl -X PATCH https://api-prod.getpocketpass.com/api/v1/passes/member-10248 \
  -H "Authorization: Bearer pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "passContent": { "tier": { "value": "Platinum" } } }'

The pass in the customer's wallet updates by itself. See Live pass updates.

The response shape

Success:

{ "data": { "id": "...", "type": "pass", "attributes": { } } }

Failure:

{ "error": { "code": "invalid_request", "message": "..." } }

Both are consistent across every endpoint, so you can write one handler. See API errors and rate limits.

What else you can do

Full detail in the API reference.

Where to go next

• API keys and authentication.
• Creating passes over the API - the patterns that matter at volume.
• External IDs and idempotency - read this before you write your integration.
• Webhooks - so your system learns when passes are installed.