API Reference

Getting started

Mint a key in Passdesk under Settings → 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>"

The same key also works with the Passdesk MCP server, which connects AI assistants such as Claude, ChatGPT, Codex and Cursor without any integration code.

Partner access for enquiries

If you build websites or phone-answering services for driving schools, you don’t need each school’s API key, and the schools don’t need the Scale plan. Register your app once with POST /api/oauth/register, then send each school owner to https://app.passdesk.co.uk/oauth/authorize with scope=enquiries:write (or enquiries:read). They click Allow, you exchange the code at POST /api/oauth/token, and the resulting pdsk_at_… bearer works on the /enquiries endpoints below for that school only. It reaches nothing else. The flow is standard OAuth 2.1 with PKCE — the MCP guide walks through the same steps. Schools can disconnect you at any time from their API keys page.

The redirect back to you carries iss alongside the code or error. Check it matches the issuer in /.well-known/oauth-authorization-server. If the authorisation link includes resource, send the same value at the token exchange or leave it out. A different one is refused with invalid_target.

The learner that /enquiries/{id}/convert returns leaves out their date of birth, licence number and guardian details. To get them back, add students:sensitive:read to the scope; the school owner then sees a separate, unticked box for it on the consent screen, and you only get the scope if they tick it. Check the scope in the token response.

curl -X POST https://app.passdesk.co.uk/api/v1/enquiries \
  -H "Authorization: Bearer pdsk_at_<token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Amy Patel","phone":"07700 900123",
       "message":"Wants automatic lessons, weekday evenings",
       "source":"phone","externalRef":"call-8f21c3"}'

Webhook delivery is available from the Team plan. The school adds the endpoint in the app — an enquiries grant can’t register one — so for Pro and Instructor schools, or until the school has set one up, poll GET /enquiries?updatedSince=… with your last sync time instead. Timestamps you send need an offset (Z or +01:00); one without is refused rather than guessed.

To book a first lesson, read GET /enquiries/availability for the times the school offers, then pass one as lesson.startTime when you convert the enquiry. If the school uses instructor regions, add enquiryId to the availability call so you see the instructors convert will book. The time is checked again at booking, so a slot taken in between comes back as a 409 slot_taken before anyone is created, and you can offer another time. A read grant is enough for availability; converting needs enquiries:write. When a school deletes an enquiry you hear about it through the enquiry.deleted webhook or GET /enquiries/deletions.

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. For a school outside the UK the units are its own currency’s (cents for euros): GET /me returns the school’s currency as an ISO code.
• 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 or access token, 402 = any request while the subscription has lapsed, or an API key on a school that isn’t on Scale, 403 = read-only key or grant on a write, or an OAuth grant without a scope for this endpoint (code: insufficient_scope), 404 = not found in your tenant, 409 = conflict (e.g. booking a slot that’s already taken), 410 = an enquiry retried after the school deleted it, 413 = an enquiry field over its cap, 429 = rate limited.
• Rate limits: per-key, 600 reads/min and 120 writes/min. RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers on every response that reaches the limiter (a 401, 402 or read-only 403 is refused before it); 429 with Retry-After on overage.

Endpoints & objects

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

{
  "data": {
    "clientId": 42,
    "apiKeyId": 7,
    "readOnly": false,
    "scopes": [],
    "currency": "GBP"
  }
}

{
  "data": {
    "id": 118,
    "firstName": "Amelia",
    "lastName": "Hart",
    "email": "[email protected]",
    "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,
    "guardianName": "Simon Hart",
    "guardianEmail": "[email protected]",
    "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.",
    "kind": "LESSON_PACKAGE",
    "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,
    "description": null,
    "amountMinorUnits": 32000,
    "notes": null,
    "status": "CONFIRMED",
    "kind": "PACKAGE",
    "adjustmentMinutes": null,
    "parentScheduleId": null,
    "refundedAt": null,
    "refundAmountMinorUnits": 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": "[email protected]",
    "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": "[email protected]",
    "name": "Priya Shah",
    "role": "EMPLOYEE",
    "permissions": [
      "VIEW_STUDENTS",
      "MANAGE_SCHEDULES",
      "VIEW_PURCHASES"
    ],
    "isInstructor": false
  }
}

{
  "data": {
    "id": 311,
    "name": "Amy Patel",
    "email": "[email protected]",
    "phone": "07700 900123",
    "message": "Wants automatic lessons, weekday evenings",
    "source": "oblyx:phone",
    "status": "NEW",
    "notes": null,
    "externalRef": "call-8f21c3",
    "studentId": null,
    "contactedAt": null,
    "resolvedAt": null,
    "convertedAt": null,
    "postcode": "G12 8QQ",
    "transmission": "AUTOMATIC",
    "preferredDaysOfWeek": [
      2,
      6
    ],
    "preferredHourStart": 17,
    "preferredHourEnd": 20,
    "preferredInstructorId": null,
    "productId": null,
    "details": [
      {
        "label": "Previous experience",
        "value": "About 10 hours elsewhere"
      }
    ],
    "privacyConsentAt": "2026-09-12T09:57:40.000Z",
    "marketingOptIn": false,
    "region": null,
    "createdAt": "2026-09-12T09:58:12.000Z",
    "updatedAt": "2026-09-12T09:58:12.000Z"
  }
}

{
  "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 when you create a key for a sync or reporting integration that doesn’t write. A read-only key gets a 403 on any POST, PUT, PATCH, or DELETE to the REST endpoints. Over MCP it gets the read-only tools.

Key scopes

Two extra powers are separate boxes on the key dialog, both off unless you tick them. GET /me lists the ones a key holds under scopes. Rotating a key keeps them, and a key can’t gain one later: create a new key instead.

• students:sensitive:read adds learners’ date of birth, provisional licence number and parent or guardian contacts to student records, here and over MCP. Without it those fields are left out of the response.
• mcp:write lets an AI assistant connected with the key book and cancel lessons over MCP. It needs a full-access key. The REST write endpoints only need full access.

Learners’ health notes are never returned by the API or MCP, whatever the key holds.

Webhooks

Subscribe an HTTPS endpoint to domain events to receive HMAC-signed JSON payloads as they happen. Available from the Team plan: manage endpoints in the workspace under Webhooks, or on Scale 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 event-specific — inspect real payloads for your events in the delivery log. For the two enquiry events it is the whole enquiry object above, plus clientId; enquiry.deleted carries only its id, externalRef, clientId and deletedAt.

{
  "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.