API Reference

Getting started

Mint a key in Passdesk under Your school → API Keys. The plaintext is shown once at creation — copy it then; we don't store it. Pass the token as a Bearer header on every request:

curl https://app.passdesk.co.uk/api/v1/students \
  -H "Authorization: Bearer pdsk_live_<prefix>_<secret>"

Connecting an AI assistant instead of writing code? The same key powers our MCP server — Claude, ChatGPT, Codex, Cursor, and friends, no integration work needed.

Conventions

• Base URL: https://app.passdesk.co.uk/api/v1
• Auth: Authorization: Bearer pdsk_live_…
• Money: always an integer in minor currency units (pence). A field named *MinorUnits holding 3500 means £35.00. Purchase.refundAmount is also pence, despite the legacy name.
• Timestamps: ISO 8601 UTC strings, e.g. 2026-08-14T16:00:00.000Z. Date filters (?from, ?to) also accept a bare YYYY-MM-DD, which is interpreted in your school's timezone — start-of-day for from, end-of-day for to.
• Stable fields: every field documented on an object below is always present in the response. Nullable fields return null when unset — they are never omitted.
• Pagination: ?limit (max 200, default 50) + ?offset. Values above the max are clamped, not rejected. Total count is in pagination.total and the X-Total-Count header.
• Response envelope: lists are { data: [...], pagination: { limit, offset, total } }; detail responses are { data: { ... } }.
• Errors: { error: string, code?: string } with HTTP status. 400 = validation failed (the message says which field), 401 = missing/invalid key, 402 = not on Scale or subscription inactive, 403 = read-only key on a write, 404 = not found in your tenant, 409 = conflict (e.g. retrying an already-delivered webhook), 429 = rate limited.
• Rate limits: per-key, 600 reads/min and 120 writes/min. Standard RateLimit-Limit / RateLimit-Remaining headers on every response; 429 with Retry-After on overage.

Endpoints & objects

Each group lists its endpoints, any query parameters, and the full field reference for the object it returns — with a type and an example for every field.

{
  "data": {
    "clientId": 42,
    "apiKeyId": 7,
    "readOnly": false
  }
}

{
  "data": {
    "id": 118,
    "firstName": "Amelia",
    "lastName": "Hart",
    "email": "amelia.hart@example.com",
    "phone": "07700 900123",
    "address": "14 Marsh Lane, Leeds LS1 4AB",
    "dateOfBirth": "2007-03-22T00:00:00.000Z",
    "gender": "female",
    "wearsGlassesOrContacts": false,
    "licenseCategory": "B",
    "profileComplete": true,
    "provisionalLicenceNumber": "HART9037226AM9XY",
    "licenceIssueDate": "2024-04-02T00:00:00.000Z",
    "theoryTestPassDate": "2026-05-11T00:00:00.000Z",
    "theoryTestCertificate": "155593301",
    "practicalTestDate": "2026-09-14T00:00:00.000Z",
    "practicalTestResult": "pending",
    "testCentreId": 211,
    "medicalConditions": null,
    "guardianName": "Simon Hart",
    "guardianEmail": "simon.hart@example.com",
    "guardianPhone": "07700 900124",
    "guardianRelationship": "father",
    "transmission": "MANUAL",
    "defaultMeetingMode": "PICKUP",
    "preferredDaysOfWeek": [
      1,
      3,
      6
    ],
    "preferredHourStart": 16,
    "preferredHourEnd": 19,
    "preferredInstructorId": 12
  }
}

{
  "data": {
    "id": 5804,
    "date": "2026-08-14T00:00:00.000Z",
    "startTime": "2026-08-14T16:00:00.000Z",
    "endTime": "2026-08-14T18:00:00.000Z",
    "studentId": 118,
    "instructorId": 12,
    "status": "COMPLETED",
    "notes": "Focus on roundabouts",
    "lessonType": "practical",
    "vehicleReg": "AB12 XYZ",
    "canceledAt": null,
    "canceledReason": null,
    "rescheduleOfId": null,
    "startedAt": "2026-08-14T16:02:11.000Z",
    "endedAt": "2026-08-14T17:58:40.000Z",
    "billableMinutes": 120,
    "distanceMiles": 23
  }
}

{
  "data": {
    "id": 31,
    "name": "10-hour lesson package",
    "description": "Ten hours of one-to-one tuition, bookable in 1-2 hour slots.",
    "priceMinorUnits": 32000,
    "priceWasMinorUnits": 35000,
    "totalMinutes": 600,
    "allowedDurations": [
      60,
      90,
      120
    ],
    "defaultLessonMinutes": 120,
    "depositMinorUnits": 5000,
    "cancelFeeMinorUnits": 2500,
    "noShowFeeMinorUnits": 3200,
    "sellableOnline": true,
    "transmission": "MANUAL",
    "displayOrder": 1
  }
}

{
  "data": {
    "id": 902,
    "studentId": 118,
    "productId": 31,
    "amountMinorUnits": 32000,
    "notes": null,
    "status": "CONFIRMED",
    "kind": "PACKAGE",
    "parentScheduleId": null,
    "refundedAt": null,
    "refundAmount": null,
    "confirmedAt": "2026-08-01T09:14:03.000Z",
    "createdAt": "2026-08-01T09:13:41.000Z"
  }
}

{
  "data": {
    "id": 44712,
    "studentId": 118,
    "date": "2026-08-14T17:58:40.000Z",
    "competency": "roundabouts",
    "rating": 4,
    "category": "practical",
    "notes": "Confident on mini-roundabouts; multi-lane still needs prompting."
  }
}

{
  "data": {
    "id": 12,
    "email": "dan.okafor@example.com",
    "name": "Dan Okafor",
    "role": "EMPLOYEE",
    "isInstructor": true,
    "hourlyRateMinorUnits": 3600,
    "employmentType": "FULL_TIME",
    "contractedHoursPerWeek": 38,
    "workingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "workingHourStart": 8,
    "workingHourEnd": 18,
    "adiBadgeNumber": "345678",
    "adiBadgeType": "ADI",
    "adiExpiryDate": "2027-01-31T00:00:00.000Z"
  }
}

{
  "data": {
    "id": 27,
    "email": "priya.shah@example.com",
    "name": "Priya Shah",
    "role": "EMPLOYEE",
    "permissions": [
      "VIEW_STUDENTS",
      "MANAGE_SCHEDULES",
      "VIEW_PURCHASES"
    ],
    "isInstructor": false
  }
}

{
  "data": {
    "id": 3,
    "url": "https://example.com/hooks/passdesk",
    "description": "CRM sync",
    "events": [
      "student.created",
      "lesson.completed"
    ],
    "active": true,
    "disabledAt": null,
    "disabledReason": null,
    "createdById": 4,
    "createdAt": "2026-07-30T10:00:00.000Z",
    "updatedAt": "2026-07-30T10:00:00.000Z",
    "signingSecret": "4f6a2c9e8b1d3f5a7c0e2b4d6f8a1c3e5b7d9f0a2c4e6b8d0f1a3c5e7b9d1f3a"
  }
}

Read-only keys

Tick the read-only box at creation time for sync / reporting integrations that don't need to mutate. A read-only key is a hard 403 on any POST, PUT, PATCH, or DELETE across the entire surface, regardless of which endpoint is called.

Webhooks

Subscribe an HTTPS endpoint to domain events and receive HMAC-signed JSON payloads when things happen. No polling required. Manage endpoints in the workspace under Webhooks, or programmatically via the /webhooks endpoints above.

Envelope

Every dispatch posts JSON of this shape, with Idempotency-Key, Passdesk-Event, and Passdesk-Signature headers. The data object is a compact event-specific summary — inspect real payloads for your events in the delivery log.

{
  "id": "evt_9f2c41d68a0b73e5c1d24f80",  // string — "evt_" + 24 hex chars; doubles as Idempotency-Key
  "type": "lesson.completed",            // string — one of the event types below
  "createdAt": "2026-08-14T18:00:04Z",   // ISO 8601 UTC
  "tenantId": 42,                        // integer — your school's id
  "apiVersion": "v1",                    // string
  "data": { ... }                        // object — shape depends on type
}

Event types

Verifying signatures

The Passdesk-Signature header has the form t=<unix>,v1=<hex>. The signed string is `${t}.${rawBody}`, HMAC-SHA256 with your endpoint's 64-hex-char signing secret. Compare in constant time. Reject anything where |now - t| exceeds 5 minutes.

// Node.js (no dependencies)
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=')),
  );
  const t = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - t) > 5 * 60) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(parts.v1, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retry behaviour

The first attempt fires immediately; failures retry on an exponential schedule: 30s, 2m, 10m, 1h, 6h, 24h. After seven attempts the row is marked failed; you can re-send it from the delivery log or via POST /webhooks/{id}/deliveries/{deliveryId}/retry. We deliver at-least-once — dedupe on the envelope's id (it's stable across retries). Ordering is not guaranteed; reconcile on createdAt.