API Documentation

Contents

• Authentication
• Base URL
• Rate Limits
• Error Codes
• Endpoints
  • GET /passes
  • POST /passes
  • GET /passes/:id
  • PATCH /passes/:id
  • POST /passes/:id/activate
  • POST /passes/:id/revoke
  • POST /scan
  • GET /clients
  • POST /clients
  • GET /clients/:id
  • GET /webhooks
  • POST /webhooks
  • DELETE /webhooks/:id
  • GET /triggers
• Examples

Authentication

All API requests require a valid API key sent in the Authorization header. API keys can be created in the Dashboard → API section (Pro plan, admin only).

Authorization: Bearer 2pk_your_api_key_here

Base URL

https://your-domain.com/api/v1

All endpoints below are relative to this base URL. CORS is enabled — preflight OPTIONS is supported on every endpoint.

Rate Limits

• 30 requests per minute per API key for /passes, /clients, /scan
• 10 requests per minute per API key for /webhooks and /triggers
• Rate limit headers in responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• When rate limited, a 429 response includes a Retry-After header

Error Codes

All errors return JSON: { "error": "message" }

Endpoints

GET/passesList Passes

Query Parameters

Response (200)

[
  {
    "id": "clx1abc...",
    "code": "AbCd1234EfGh",
    "name": "VIP Guest",
    "type": "single",
    "status": "active",
    "usagesCount": 0,
    "maxUsages": null,
    "validFrom": null,
    "validUntil": "2025-12-31T23:59:59.000Z",
    "client": { "name": "John Doe", "email": "[email protected]" },
    "publicUrl": "https://your-domain.com/p/AbCd1234EfGh?token=...",
    "createdAt": "2025-06-01T12:00:00.000Z"
  }
]

POST/passesCreate a Pass

Request Body

Response (201)

{
  "id": "clx1abc...",
  "code": "AbCd1234EfGh",
  "name": "VIP Guest",
  "type": "single",
  "status": "active",
  "maxUsages": null,
  "usagesCount": 0,
  "validFrom": null,
  "validUntil": "2025-12-31T23:59:59.000Z",
  "publicUrl": "https://your-domain.com/p/AbCd1234EfGh?token=...",
  "createdAt": "2025-06-01T12:00:00.000Z"
}

GET/passes/:passIdGet Pass

Returns the full pass including custom fields and attached client.

Response (200)

{
  "id": "clx1abc...",
  "code": "AbCd1234EfGh",
  "name": "VIP Guest",
  "type": "single",
  "status": "active",
  "usagesCount": 0,
  "maxUsages": null,
  "validFrom": null,
  "validUntil": "2025-12-31T23:59:59.000Z",
  "fields": [
    { "key": "Full Name", "value": "John Doe", "isPublic": true }
  ],
  "client": {
    "id": "clx2...", "name": "John Doe", "email": "[email protected]", "phone": null
  },
  "publicUrl": "https://your-domain.com/p/AbCd1234EfGh?token=...",
  "createdAt": "2025-06-01T12:00:00.000Z",
  "updatedAt": "2025-06-01T12:00:00.000Z"
}

PATCH/passes/:passIdUpdate Pass

Request Body

When customFields is provided, all existing fields are replaced. Status change emits a pass.status_changed webhook.

POST/passes/:passId/activateActivate Pass

Sets status to active. Returns 400 if already active. Emits pass.status_changed and notifies wallet apps.

Response (200)

{ "id": "clx1abc...", "code": "AbCd1234EfGh", "name": "VIP Guest", "status": "active" }

POST/passes/:passId/revokeRevoke Pass

Sets status to revoked. Returns 400 if already revoked. Emits pass.status_changed and notifies wallet apps.

Response (200)

{ "id": "clx1abc...", "code": "AbCd1234EfGh", "name": "VIP Guest", "status": "revoked" }

POST/scanScan Pass

Request Body

Validates the pass against status, validity dates, and usage limits. Records a scan and emits pass.scanned.single passes flip to used after the first successful scan.

Response (200)

{
  "success": true,
  "result": "success",
  "pass": {
    "id": "clx1abc...",
    "code": "AbCd1234EfGh",
    "name": "VIP Guest",
    "type": "single",
    "status": "used",
    "usagesCount": 1,
    "maxUsages": null
  },
  "scan": { "id": "clx3...", "scannedAt": "2025-06-01T12:30:00.000Z" }
}

On failure, response is 200 with success: false and result:revoked, already_used, not_yet_valid, expired, max_usages_reached.

GET/clientsList Clients

Query Parameters

Response (200)

[
  {
    "id": "clx2...",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "notes": null,
    "createdAt": "2025-06-01T12:00:00.000Z"
  }
]

POST/clientsCreate Client

Request Body

Response (201)

{
  "id": "clx2...",
  "name": "John Doe",
  "email": "[email protected]",
  "phone": null,
  "notes": null,
  "createdAt": "2025-06-01T12:00:00.000Z"
}

Emits client.created webhook.

GET/clients/:clientIdGet Client

Response (200)

{
  "id": "clx2...",
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "+1234567890",
  "notes": "VIP customer",
  "createdAt": "2025-06-01T12:00:00.000Z"
}

GET/webhooksList Webhooks

Response (200)

[
  {
    "id": "wh_...",
    "event": "pass.scanned",
    "targetUrl": "https://example.com/hook",
    "active": true,
    "createdAt": "2025-06-01T12:00:00.000Z"
  }
]

POST/webhooksSubscribe Webhook

Request Body

Tenant has a fixed webhook quota — exceeding it returns 403. Subscribed events POST a JSON payload to targetUrl.

Response (201)

{
  "id": "wh_...",
  "event": "pass.scanned",
  "targetUrl": "https://example.com/hook",
  "active": true,
  "createdAt": "2025-06-01T12:00:00.000Z"
}

DELETE/webhooks/:webhookIdUnsubscribe Webhook

Response (200)

{ "success": true }

GET/triggersPoll Triggers

Polling fallback used by Zapier. Returns recent items for the requested event since a given timestamp.

Query Parameters

Each event returns a different shape — for pass.created the items match the list-passes response with extra fields, clientName, clientEmail, clientPhone; for pass.scanned each item is a flat scan record; for pass.status_changed a pass with changedAt; for client.created the client record.

Examples

curl — create pass

curl -X POST https://your-domain.com/api/v1/passes \
  -H "Authorization: Bearer 2pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "name": "VIP Guest",
    "validUntil": "2025-12-31T23:59:59Z",
    "customFields": [
      { "key": "Full Name", "value": "John Doe", "isPublic": true }
    ]
  }'

curl — scan pass

curl -X POST https://your-domain.com/api/v1/scan \
  -H "Authorization: Bearer 2pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "code": "AbCd1234EfGh" }'

curl — subscribe webhook

curl -X POST https://your-domain.com/api/v1/webhooks \
  -H "Authorization: Bearer 2pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "pass.scanned",
    "targetUrl": "https://example.com/hook"
  }'

JavaScript (fetch)

const response = await fetch("https://your-domain.com/api/v1/passes", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 2pk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "single",
    name: "VIP Guest",
    customFields: [
      { key: "Full Name", value: "John Doe", isPublic: true }
    ],
  }),
});

const data = await response.json();
console.log(data.publicUrl);