Park Sync API Docs

REST + webhooks reference for the Park Sync Public Partner API (v1).

Overview

The Park Sync partner API lets third-party tools read and write parks data on behalf of park admins who have installed your app. All endpoints live under https://parksync.net/api/v1 and speak JSON. Authorization is OAuth 2.0 authorization-code flow; after install you hold an access token scoped to a single park (or operator) installation.

Register your app at /developers/apps and copy the client id plus secret.
Direct park admins to the OAuth consent screen to install your app on a specific park.
Exchange the returned authorization code for an access token at /api/oauth/token.
Call the REST API below. Subscribe to webhooks for live updates.

Apps start in pending_review and can only install against sandbox parks until approved. A machine-readable OpenAPI 3.1 document of every endpoint is available at /api/v1/openapi.json.

Authentication

Park Sync uses the OAuth 2.0 authorization-code flow (RFC 6749). The steps below describe the handshake end-to-end.

1. Redirect the park admin to the consent screen

url

GET /oauth/authorize?response_type=code
       &client_id=<app_id>
       &redirect_uri=<your-callback-url>
       &scope=<space-separated-scopes>
       &state=<opaque-csrf-token>

On approval, Park Sync redirects back to your redirect_uri with ?code=...&state=.... Verify state before continuing.

2. Exchange the authorization code for tokens

POST /api/oauth/token with application/x-www-form-urlencoded body and grant_type=authorization_code.

curl

curl -X POST https://parksync.net/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=<code-from-callback> \
  -d redirect_uri=https://your-app.example/callback \
  -d client_id=<app_id> \
  -d client_secret=<client_secret>

node.js

const res = await fetch('https://parksync.net/api/oauth/token', {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: '<code-from-callback>',
    redirect_uri: 'https://your-app.example/callback',
    client_id: '<app_id>',
    client_secret: '<client_secret>',
  }),
});
const { access_token, refresh_token } = await res.json();

python

import requests

res = requests.post('https://parksync.net/api/oauth/token', data={
    'grant_type': 'authorization_code',
    'code': '<code-from-callback>',
    'redirect_uri': 'https://your-app.example/callback',
    'client_id': '<app_id>',
    'client_secret': '<client_secret>',
})
tokens = res.json()

The response body is:

json

{
  "access_token": "psa_live_<opaque>",
  "refresh_token": "psr_live_<opaque>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "reservations:read reservations:write",
  "installation_id": "11111111-1111-1111-1111-111111111111"
}

Access tokens have the prefix psa_live_ and a one-hour lifetime. Refresh tokens have the prefix psr_live_ and live for thirty days.

3. Refresh an expired access token

curl

curl -X POST https://parksync.net/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=<refresh-token> \
  -d client_id=<app_id> \
  -d client_secret=<client_secret>

4. Revoke a token

curl

curl -X POST https://parksync.net/api/oauth/revoke \
  -d token=<access-or-refresh-token> \
  -d client_id=<app_id> \
  -d client_secret=<client_secret>

Revoking a refresh token also invalidates any access token issued from it.

Calling the API

Pass the access token as a bearer token in the Authorization header:

http

GET /api/v1/reservations HTTP/1.1
Host: parksync.net
Authorization: Bearer psa_live_...

Scopes

Scopes are requested in the authorize URL and granted by the installing admin. Endpoints that require a specific scope return 403 insufficient_scope when the access token lacks it.

Scope	Name	Description
reservations:read	Read reservations	View booking data for the installed park or operator.
reservations:write	Create and cancel reservations	Book and cancel on behalf of patrons.
payments:read	Read payment events	See successful charges, refunds, and disputes.
patrons:read	Read patron profiles (limited)	Name, masked email, created_at.
patrons:full	Read patron profiles (full Personally Identifiable Information)	Includes email, phone, address.
memberships:read	Read memberships	View membership tiers and subscriber status.
memberships:write	Manage memberships	Create and cancel member subscriptions.
invoices:read	Read invoices	View invoicing and aging status.
waitlist:read	Read waitlist	View court waitlist offers and claims.
audit:read	Read audit events	View admin action trail (requires M57).
reports:read	Read reports	View scheduled report definitions (requires M59).

Endpoints

Every endpoint requires a valid bearer token. Scopes listed under "Required scopes" are additional to the baseline 401 / 403 / 429 / 503 envelope that every route returns on failure.

Courts

get/api/v1/courts

List courts

Lists courts across parks the installation has access to. Supports keyset pagination.

Required scopes: None beyond a valid access token.

Query parameters

Name	Type	Required
park_id	string (uuid)	no
cursor	string	no
limit	integer	no

200 response

json

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "park_id": "11111111-1111-1111-1111-111111111111",
      "name": "example",
      "sport": "example",
      "surface": "example",
      "indoor": true,
      "active": true,
      "capacity": 0,
      "duration_default_minutes": 0,
      "created_at": "example"
    }
  ],
  "next_cursor": "example"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/courts" \
  -H "Authorization: Bearer <access-token>"

Invoices

get/api/v1/invoices

List invoices

Required scopes

invoices:read

Query parameters

Name	Type	Required
park_id	string (uuid)	no
cursor	string	no
limit	integer	no

200 response

json

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "park_id": "11111111-1111-1111-1111-111111111111",
      "period_start": "example",
      "period_end": "example",
      "amount_cents": 0,
      "tax_cents": 0,
      "total_cents": 0,
      "currency": "example",
      "status": "draft",
      "due_date": "example",
      "po_number": "example",
      "payment_method": "ach",
      "paid_at": "2026-05-01T12:00:00.000Z",
      "created_at": "2026-05-01T12:00:00.000Z"
    }
  ],
  "next_cursor": "example"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/invoices" \
  -H "Authorization: Bearer <access-token>"

get/api/v1/invoices/{id}

Retrieve an invoice

Required scopes

invoices:read

Path parameters

Name	Type	Required
id	string (uuid)	yes

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "park_id": "11111111-1111-1111-1111-111111111111",
  "period_start": "example",
  "period_end": "example",
  "amount_cents": 0,
  "tax_cents": 0,
  "total_cents": 0,
  "currency": "example",
  "status": "draft",
  "due_date": "example",
  "po_number": "example",
  "payment_method": "ach",
  "paid_at": "2026-05-01T12:00:00.000Z",
  "created_at": "2026-05-01T12:00:00.000Z"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/invoices/{id}" \
  -H "Authorization: Bearer <access-token>"

Memberships

get/api/v1/memberships

List membership tiers

Required scopes

memberships:read

Query parameters

Name	Type	Required
park_id	string (uuid)	no
cursor	string	no
limit	integer	no

200 response

json

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "park_id": "11111111-1111-1111-1111-111111111111",
      "name": "example",
      "cadence": "monthly",
      "price_cents": 0,
      "active": true,
      "created_at": "2026-05-01T12:00:00.000Z"
    }
  ],
  "next_cursor": "example"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/memberships" \
  -H "Authorization: Bearer <access-token>"

post/api/v1/memberships

Start a membership checkout

Starts a Stripe Checkout session for the patron to subscribe to a membership tier. The subscription row is created server-side on checkout completion via the existing webhook path — never synchronously.

Required scopes

memberships:write

Request body

json

{
  "membership_id": "11111111-1111-1111-1111-111111111111",
  "primary_patron_id": "11111111-1111-1111-1111-111111111111",
  "success_url": "https://example.com",
  "cancel_url": "https://example.com"
}

201 response

json

{
  "checkout_url": "https://example.com",
  "subscription_id": "11111111-1111-1111-1111-111111111111"
}

Example

curl

curl -X POST "https://parksync.net/api/v1/memberships" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"membership_id":"11111111-1111-1111-1111-111111111111","primary_patron_id":"11111111-1111-1111-1111-111111111111","success_url":"https://example.com","cancel_url":"https://example.com"}'

get/api/v1/memberships/{id}

Retrieve a membership tier

Required scopes

memberships:read

Path parameters

Name	Type	Required
id	string (uuid)	yes

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "park_id": "11111111-1111-1111-1111-111111111111",
  "name": "example",
  "cadence": "monthly",
  "price_cents": 0,
  "active": true,
  "created_at": "2026-05-01T12:00:00.000Z"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/memberships/{id}" \
  -H "Authorization: Bearer <access-token>"

get/api/v1/memberships/subscriptions

List membership subscriptions

Required scopes

memberships:read

Query parameters

Name	Type	Required
park_id	string (uuid)	no
cursor	string	no
limit	integer	no

200 response

json

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "membership_id": "11111111-1111-1111-1111-111111111111",
      "primary_patron_id": "11111111-1111-1111-1111-111111111111",
      "status": "active",
      "started_at": "2026-05-01T12:00:00.000Z",
      "expires_at": "2026-05-01T12:00:00.000Z",
      "auto_renew": true,
      "created_at": "2026-05-01T12:00:00.000Z"
    }
  ],
  "next_cursor": "example"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/memberships/subscriptions" \
  -H "Authorization: Bearer <access-token>"

get/api/v1/memberships/subscriptions/{id}

Retrieve a membership subscription

Required scopes

memberships:read

Path parameters

Name	Type	Required
id	string (uuid)	yes

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "membership_id": "11111111-1111-1111-1111-111111111111",
  "primary_patron_id": "11111111-1111-1111-1111-111111111111",
  "status": "active",
  "started_at": "2026-05-01T12:00:00.000Z",
  "expires_at": "2026-05-01T12:00:00.000Z",
  "auto_renew": true,
  "created_at": "2026-05-01T12:00:00.000Z"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/memberships/subscriptions/{id}" \
  -H "Authorization: Bearer <access-token>"

delete/api/v1/memberships/subscriptions/{id}

Cancel a membership subscription

Cancels a subscription. Defaults to end-of-period cancellation so the patron keeps access through the paid period; pass `immediate=true` to terminate access at the end of the current Stripe billing window and stop further billing.

Required scopes

memberships:write

Path parameters

Name	Type	Required
id	string (uuid)	yes

Query parameters

Name	Type	Required
immediate	enum (true \| false)	no

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "membership_id": "11111111-1111-1111-1111-111111111111",
  "primary_patron_id": "11111111-1111-1111-1111-111111111111",
  "status": "active",
  "started_at": "2026-05-01T12:00:00.000Z",
  "expires_at": "2026-05-01T12:00:00.000Z",
  "auto_renew": true,
  "created_at": "2026-05-01T12:00:00.000Z"
}

Example

curl

curl -X DELETE "https://parksync.net/api/v1/memberships/subscriptions/{id}" \
  -H "Authorization: Bearer <access-token>"

Parks

get/api/v1/parks/{id}

Retrieve a park

Returns the park at the given ID if it is within the installation scope.

Required scopes: None beyond a valid access token.

Path parameters

Name	Type	Required
id	string (uuid)	yes

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "slug": "example",
  "name": "example",
  "operator_account_id": "11111111-1111-1111-1111-111111111111",
  "customer_type": "private_operator",
  "billing_mode": "platform_fee",
  "timezone": "example",
  "sports_offered": [
    "example"
  ],
  "address": "example",
  "city": "example",
  "state": "example",
  "zip": "example",
  "created_at": "example"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/parks/{id}" \
  -H "Authorization: Bearer <access-token>"

Patrons

get/api/v1/patrons

List patrons

Lists patrons (profiles with at least one reservation at an in-scope park). Rows carry the limited DTO by default; installations with `patrons:full` receive email, phone, and patron_type.

Required scopes

patrons:read

Query parameters

Name	Type	Required
park_id	string (uuid)	no
cursor	string	no
limit	integer	no

200 response

json

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "park_id": "11111111-1111-1111-1111-111111111111",
      "first_name": "example",
      "last_name": "example",
      "email_masked": "example",
      "created_at": "example",
      "email": "example",
      "phone": "example",
      "patron_type": "resident"
    }
  ],
  "next_cursor": "example"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/patrons" \
  -H "Authorization: Bearer <access-token>"

get/api/v1/patrons/{id}

Retrieve a patron

Returns the patron at the given ID if they have at least one reservation at an accessible park.

Required scopes

patrons:read

Path parameters

Name	Type	Required
id	string (uuid)	yes

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "park_id": "11111111-1111-1111-1111-111111111111",
  "first_name": "example",
  "last_name": "example",
  "email_masked": "example",
  "created_at": "example",
  "email": "example",
  "phone": "example",
  "patron_type": "resident"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/patrons/{id}" \
  -H "Authorization: Bearer <access-token>"

Reservations

get/api/v1/reservations

List reservations

Lists reservations across accessible parks. Filter by park, status, or `since` timestamp.

Required scopes

reservations:read

Query parameters

Name	Type	Required
park_id	string (uuid)	no
status	enum (pending_payment \| confirmed \| cancelled \| completed \| refunded \| no_show)	no
since	string (date-time)	no
cursor	string	no
limit	integer	no

200 response

json

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "park_id": "11111111-1111-1111-1111-111111111111",
      "court_id": "11111111-1111-1111-1111-111111111111",
      "player_id": "11111111-1111-1111-1111-111111111111",
      "starts_at": "2026-05-01T12:00:00.000Z",
      "ends_at": "2026-05-01T12:00:00.000Z",
      "status": "pending_payment",
      "total_cents": 0,
      "platform_fee_cents": 0,
      "created_at": "2026-05-01T12:00:00.000Z",
      "canceled_at": "2026-05-01T12:00:00.000Z",
      "arrived_at": "2026-05-01T12:00:00.000Z"
    }
  ],
  "next_cursor": "example"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/reservations" \
  -H "Authorization: Bearer <access-token>"

post/api/v1/reservations

Create a reservation

Creates a confirmed reservation. Partner-mediated — the partner is expected to have collected payment upstream. Pricing is computed via the park pricing rules; no dynamic / member discounts in v1.

Required scopes

reservations:write

Request body

json

{
  "park_id": "11111111-1111-1111-1111-111111111111",
  "court_id": "11111111-1111-1111-1111-111111111111",
  "player_id": "11111111-1111-1111-1111-111111111111",
  "starts_at": "2026-05-01T12:00:00.000Z",
  "ends_at": "2026-05-01T12:00:00.000Z",
  "patron_type": "resident"
}

201 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "park_id": "11111111-1111-1111-1111-111111111111",
  "court_id": "11111111-1111-1111-1111-111111111111",
  "player_id": "11111111-1111-1111-1111-111111111111",
  "starts_at": "2026-05-01T12:00:00.000Z",
  "ends_at": "2026-05-01T12:00:00.000Z",
  "status": "pending_payment",
  "total_cents": 0,
  "platform_fee_cents": 0,
  "created_at": "2026-05-01T12:00:00.000Z",
  "canceled_at": "2026-05-01T12:00:00.000Z",
  "arrived_at": "2026-05-01T12:00:00.000Z"
}

Example

curl

curl -X POST "https://parksync.net/api/v1/reservations" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"park_id":"11111111-1111-1111-1111-111111111111","court_id":"11111111-1111-1111-1111-111111111111","player_id":"11111111-1111-1111-1111-111111111111","starts_at":"2026-05-01T12:00:00.000Z","ends_at":"2026-05-01T12:00:00.000Z","patron_type":"resident"}'

get/api/v1/reservations/{id}

Retrieve a reservation

Required scopes

reservations:read

Path parameters

Name	Type	Required
id	string (uuid)	yes

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "park_id": "11111111-1111-1111-1111-111111111111",
  "court_id": "11111111-1111-1111-1111-111111111111",
  "player_id": "11111111-1111-1111-1111-111111111111",
  "starts_at": "2026-05-01T12:00:00.000Z",
  "ends_at": "2026-05-01T12:00:00.000Z",
  "status": "pending_payment",
  "total_cents": 0,
  "platform_fee_cents": 0,
  "created_at": "2026-05-01T12:00:00.000Z",
  "canceled_at": "2026-05-01T12:00:00.000Z",
  "arrived_at": "2026-05-01T12:00:00.000Z"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/reservations/{id}" \
  -H "Authorization: Bearer <access-token>"

delete/api/v1/reservations/{id}

Cancel a reservation

Cancels a reservation. Refunds are handled separately per the park refund policy.

Required scopes

reservations:write

Path parameters

Name	Type	Required
id	string (uuid)	yes

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "park_id": "11111111-1111-1111-1111-111111111111",
  "court_id": "11111111-1111-1111-1111-111111111111",
  "player_id": "11111111-1111-1111-1111-111111111111",
  "starts_at": "2026-05-01T12:00:00.000Z",
  "ends_at": "2026-05-01T12:00:00.000Z",
  "status": "pending_payment",
  "total_cents": 0,
  "platform_fee_cents": 0,
  "created_at": "2026-05-01T12:00:00.000Z",
  "canceled_at": "2026-05-01T12:00:00.000Z",
  "arrived_at": "2026-05-01T12:00:00.000Z"
}

Example

curl

curl -X DELETE "https://parksync.net/api/v1/reservations/{id}" \
  -H "Authorization: Bearer <access-token>"

Waitlist

get/api/v1/waitlist

List waitlist entries

Required scopes

waitlist:read

Query parameters

Name	Type	Required
park_id	string (uuid)	no
cursor	string	no
limit	integer	no

200 response

json

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "park_id": "11111111-1111-1111-1111-111111111111",
      "court_id": "11111111-1111-1111-1111-111111111111",
      "patron_id": "11111111-1111-1111-1111-111111111111",
      "slot_start": "2026-05-01T12:00:00.000Z",
      "slot_end": "2026-05-01T12:00:00.000Z",
      "status": "queued",
      "rank": 0,
      "joined_at": "2026-05-01T12:00:00.000Z",
      "offer_sent_at": "2026-05-01T12:00:00.000Z",
      "offer_expires_at": "2026-05-01T12:00:00.000Z"
    }
  ],
  "next_cursor": "example"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/waitlist" \
  -H "Authorization: Bearer <access-token>"

get/api/v1/waitlist/{id}

Retrieve a waitlist entry

Required scopes

waitlist:read

Path parameters

Name	Type	Required
id	string (uuid)	yes

200 response

json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "park_id": "11111111-1111-1111-1111-111111111111",
  "court_id": "11111111-1111-1111-1111-111111111111",
  "patron_id": "11111111-1111-1111-1111-111111111111",
  "slot_start": "2026-05-01T12:00:00.000Z",
  "slot_end": "2026-05-01T12:00:00.000Z",
  "status": "queued",
  "rank": 0,
  "joined_at": "2026-05-01T12:00:00.000Z",
  "offer_sent_at": "2026-05-01T12:00:00.000Z",
  "offer_expires_at": "2026-05-01T12:00:00.000Z"
}

Example

curl

curl -X GET "https://parksync.net/api/v1/waitlist/{id}" \
  -H "Authorization: Bearer <access-token>"

Webhooks

Webhooks push events to your endpoint as they happen, so you do not have to poll the REST API for changes.

Subscribing

Configure endpoints from /developers/apps → Webhooks. For each endpoint you provide a URL (HTTPS, publicly reachable) and a list of enabled events. Park Sync returns a signing secret (whsec_...) that you should store securely — it is shown exactly once.

Request headers

Header	Meaning
X-ParkSync-Signature	`sha256=<hex>` — HMAC (hash-based message authentication code) of the signed payload, computed with your endpoint signing secret.
X-ParkSync-Timestamp	Unix seconds when the delivery was produced. Use this to reject replayed deliveries more than 300 seconds old.
X-ParkSync-Event-Id	Unique identifier for this event. Use it as your idempotency key.
X-ParkSync-Event-Type	The canonical event type, e.g. `reservation.created`.

Signature verification

The signed payload is the string `${timestamp}.${rawBody}`. Compute HMAC-SHA-256(signingSecret, signedPayload) and compare against the hex portion of X-ParkSync-Signature using a constant-time comparison.

node.js

const crypto = require('node:crypto');

function verify(req, signingSecret) {
  const sig = req.headers['x-parksync-signature'];          // "sha256=..."
  const ts  = req.headers['x-parksync-timestamp'];          // unix seconds
  if (!sig || !ts) return false;
  const received = sig.replace(/^sha256=/, '');
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${ts}.${req.rawBody}`)
    .digest('hex');
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(received, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

python

import hmac
import hashlib

def verify(headers, body, signing_secret):
    sig = headers.get('X-ParkSync-Signature', '')
    ts  = headers.get('X-ParkSync-Timestamp', '')
    if not sig or not ts:
        return False
    received = sig.removeprefix('sha256=')
    expected = hmac.new(
        signing_secret.encode(),
        f'{ts}.{body}'.encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, received)

ruby

require 'openssl'

def verify(request, signing_secret)
  sig = request.headers['X-ParkSync-Signature']
  ts  = request.headers['X-ParkSync-Timestamp']
  return false unless sig && ts

  received = sig.sub(/^sha256=/, '')
  expected = OpenSSL::HMAC.hexdigest('sha256', signing_secret, "#{ts}.#{request.raw_body}")
  Rack::Utils.secure_compare(expected, received)
end

Canonical events

Event	Description
reservation.created	A reservation was created.
reservation.updated	A reservation was updated (e.g., notes changed, details edited).
reservation.canceled	A reservation was canceled.
reservation.arrived	A patron checked in at the start of their reservation.
reservation.no_show	A reservation was flagged as no-show after a grace period.
payment.succeeded	A payment succeeded for a reservation or subscription.
payment.refunded	A payment was refunded in whole or in part.
payment.failed	A payment attempt failed.
payment.disputed	A charge was disputed by the cardholder.
membership.created	A new membership subscription was created.
membership.renewed	A membership subscription was renewed for another period.
membership.lapsed	A membership subscription lapsed after failed renewal + grace period.
waitlist.offered	A waitlist slot opened up and an offer was sent.
waitlist.claimed	A patron claimed an available waitlist offer.
park.settings_updated	Park settings were modified by an admin.
invoice.paid	An invoice was paid.
audit.event	An audit event was recorded (requires M57; opt-in only).

Example payload

Example delivery for reservation.created:

json

{
  "id": "evt_01HV9K8NQJ1A2B3C4D5E6F7G",
  "type": "reservation.created",
  "created_at": "2026-05-01T12:00:00.000Z",
  "installation_id": "11111111-1111-1111-1111-111111111111",
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "park_id": "33333333-3333-3333-3333-333333333333",
    "court_id": "44444444-4444-4444-4444-444444444444",
    "player_id": "55555555-5555-5555-5555-555555555555",
    "starts_at": "2026-05-01T17:00:00.000Z",
    "ends_at": "2026-05-01T18:00:00.000Z",
    "status": "confirmed",
    "price_cents": 2400,
    "created_at": "2026-05-01T12:00:00.000Z"
  }
}

Retries and dead-letter

Park Sync retries non-2xx responses up to five times over roughly 24 hours with an exponential back-off: 30 seconds, 5 minutes, 30 minutes, 3 hours, 12 hours. After the fifth failure the delivery moves to the dead-letter log, visible on the Event Log tab of your app detail page. Deliveries that return 2xx within ten seconds are considered successful.

Replay

From /developers/apps → your app → Event Log, you can replay any delivery. A replay reuses the original event id so your receiver can skip duplicates idempotently.

Best practices

Verify the signature using the raw request body bytes — do not re-serialize the JSON before computing the HMAC, or the hash will not match.
Reject deliveries whose X-ParkSync-Timestamp is more than 300 seconds away from your server clock to limit replay risk.
Use X-ParkSync-Event-Id as an idempotency key — same id means same event, even on retries and manual replays.
Return 2xx as soon as you have persisted the event; do follow-up work async.

Rate limits

Each app is limited to 60 requests per minute per route. The limit is enforced per app (not per installation), so spreading traffic across installations does not earn additional budget.

When exceeded the API returns 429 rate_limited with a Retry-After header (seconds) indicating when the window resets:

http

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 23 seconds."
  }
}

Per-app increases are available on request — email hello@parksync.net with your app id and expected peak QPS.

Errors

Every error response uses the same envelope:

json

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing the reservations:write scope.",
    "details": {
      "required_scope": "reservations:write"
    }
  }
}

Code	Status	Meaning
unauthorized	401	Missing or invalid bearer token.
insufficient_scope	403	The token does not carry the scope this endpoint requires.
forbidden	403	Access denied for a reason unrelated to scope.
not_found	404	The resource does not exist, or is outside the installation scope.
bad_request	400	Request failed schema validation or business-rule checks.
method_not_allowed	405	The path exists but does not support this HTTP method.
rate_limited	429	Too many requests in the current 60-second window.
feature_disabled	503	The partner API has been disabled globally or for your app.
server_error	500	Unexpected failure. Safe to retry with exponential back-off.

Pagination

List endpoints use cursor pagination. Pass ?limit=<n> (1–100, default 50) and ?cursor=<token> to walk pages. Cursors are opaque base64 strings — round-trip the value returned in next_cursor; do not construct them yourself.

Every page includes a Link header with a rel="next" target when more rows are available. The body also carries next_cursor, which is null on the last page.

Two-page walk

http

GET /api/v1/reservations?limit=2
Authorization: Bearer psa_live_...

HTTP/1.1 200 OK
Link: <https://parksync.net/api/v1/reservations?limit=2&cursor=eyJ0IjoxfQ>; rel="next"

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111"
    },
    {
      "id": "22222222-2222-2222-2222-222222222222"
    }
  ],
  "next_cursor": "eyJ0IjoxfQ"
}

http

GET /api/v1/reservations?limit=2&cursor=eyJ0IjoxfQ
Authorization: Bearer psa_live_...

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "33333333-3333-3333-3333-333333333333"
    }
  ],
  "next_cursor": null
}

Stop when next_cursor is null.