Base URL

https://api.getpocketpass.com/api/v1

Authentication

All API requests require an API key. You can generate one from Settings > API Keys in the Pocket Dashboard.

API keys use the format pk_live_... and can be provided in one of two ways:

Method	Header	Example
API Key header (recommended)	`X-Api-Key`	`X-Api-Key: pk_live_abc123`
Bearer token	`Authorization`	`Authorization: Bearer pk_live_abc123`

# Example request
curl https://api.getpocketpass.com/api/v1/passes \
  -H "X-Api-Key: pk_live_abc123"

Note: API access requires a Growth plan or custom API access. If your plan does not include API access, requests will return a 403 Forbidden response. Keep your API keys secure — do not expose them in client-side code or public repositories.

Rate Limits

API requests are rate limited to ensure fair usage and platform stability.

Scope	Limit
Per API key	100 requests / minute
Per account	1,000 requests / hour

When a rate limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

Resources

The API provides two core resources:

Passes

Create and manage wallet passes for your customers. Each pass represents a membership card that can be installed in Apple Wallet or Google Wallet.

Method	Endpoint	Description
`POST`	`/passes`	Create a new pass
`GET`	`/passes`	List all passes
`GET`	`/passes/{id}`	Get pass details
`PATCH`	`/passes/{id}`	Update a pass
`DELETE`	`/passes/{id}`	Delete a pass
`GET`	`/passes/{id}/wallet-links`	Get Apple & Google Wallet download links
`GET`	`/passes/{id}/apple-pass`	Download the `.pkpass` file

Notifications

Send push notifications to pass holders. Notifications appear as lock screen alerts on Apple devices and as pass updates on Google Wallet.

Method	Endpoint	Description
`POST`	`/passes/{id}/notifications`	Send a push notification
`GET`	`/passes/{id}/notifications`	Get notification history

Errors

All error responses return a JSON body with error, code, and optionally details fields.

{
  "error": "A pass with this email already exists",
  "code": "duplicate_email"
}

Status	Meaning
`400`	Bad Request — invalid or missing parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — API access not enabled on your plan
`404`	Not Found — the requested resource does not exist
`409`	Conflict — resource already exists (e.g. duplicate email)
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error

Pagination

List endpoints return paginated results using the following query parameters:

Parameter	Default	Max	Description
`page`	1	—	Page number
`page_size`	50	100	Results per page

Response includes pagination metadata:

{
  "data": [...],
  "total": 142,
  "page": 1,
  "pageSize": 50,
  "hasMore": true
}