API for ski schools

Keys belong to the school, not to a person, and only the school's owner can create or revoke them, from the Connections tab of the school panel. A key is shown once, at creation; we store a hash and cannot show it again. A school may hold up to 5 live keys, so a new integration gets its own and an old one can be revoked without touching the rest. Live keys start with ap_live_; the sandbox's keys start with ap_test_ and are counted separately.

A key stops working the moment it is revoked, and every key is refused with a 403 school_not_active once the school is closed or is not approved. A school that is only suspended — hidden from the site, its page gone — keeps its keys: its bookings carry on, and the API with them. Keys cannot be managed through the API itself. To rotate one: create the new key, switch your system to it, then revoke the old one — both are valid in between. The panel shows when each key was last used, at 5-minute granularity. Keys are for servers: never ship one inside a browser or a mobile app.

Every request carries the key as a bearer token. The base URL is https://alpinepal.com/api/v1; responses are JSON, never cached, and each one carries an X-Request-Id you can quote to us. Times of day are on the resort's clock as HH:mm, dates are YYYY-MM-DD, and instants are ISO 8601 in UTC with milliseconds.

Request bodies must be JSON with a Content-Type: application/json header (415 otherwise), under 256 KB (413), and are checked strictly: an unknown field is a 400 validation_error listing the offending paths. An empty body reads as an empty object. A method the path does not support is a 405 with an Allow header; a trailing slash is a 404.

There is no CORS: the API is server to server, and a request from a browser will fail. That is on purpose, since a key in a browser is a key anybody can read.

Per key, in fixed one-minute windows: 600 reads (GET) and 120 writes (everything else, DELETE included) per minute. Beyond that the answer is 429 rate_limited with a Retry-After header, in seconds. A test key has its own allowance. Failed authentication is limited per IP address, 20 in 10 minutes; past that the answer to any further guess is 429, before the key is even looked up. Webhook tests and replays share a separate allowance of 10 in 10 minutes per key, since each one is a request to somebody else's server.

Every error is the same envelope: an HTTP status, a stable code to branch on, a message for a human and the request id. Five codes carry details: a validation_error lists the offending fields as [{path, message}] (at most 10); booking_state says which state the booking is in now ({bookingStatus}); booking_conflict names the hours in the way and, when that booking is paid, its id and reference; rate_limited repeats the wait as {retryAfterSeconds}; inside_notice_window gives the instructor's notice in hours ({hours}).

Ids. Instructors carry their account id (user_…), or unclaimed_… while a profile your school added without an account has not been claimed; a school's unassigned-lessons seat is pool_<schoolId>; sandbox instructors are sandbox_ia_… and sandbox_ib_…. Bookings are b_…, events evt_…, deliveries whd_…, endpoints wh_…, requests req_…. References are AP-<year>-<5 digits> for real bookings and SB<6 hex> in the sandbox.

Times. date, startTime and endTime are the wall clock of resortTimeZone, never UTC; the instants (createdAt, updatedAt, paidAt, instructorResponseDeadline…) are UTC. A lesson on the night the clocks change resolves to the first occurrence of an ambiguous hour, and an hour that does not exist that night moves forward. endTime may be 24:00. Whether a time is in the past is judged on the resort's clock.

Money. subtotal = (hourlyPrice + extraStudentPrice × max(0, numberOfStudents − includedStudents)) × durationHours, rounded to the currency; it is what the customer pays. hourlyPrice is that of the lesson's date: a season's (seasonPrices) when the date falls in one, the instructor's or the seat's own otherwise; includedStudents is how many students it covers, 1 unless the school sets more. platformFee is our commission: 10 %, or the higher one your school has agreed with us in writing; each booking keeps the rate it was sold under. netAmount is the rest, subtotal − platformFee, credited to your school's ledger when the lesson completes, whoever taught it and whoever manages them — and voided if the booking is refunded. Every instructor on your roster charges in your school's currency; hourly prices have a floor per currency (10 EUR, 11 USD, 10 CHF) and extraStudentPrice is 0 or more. Equipment the customer rents from your school with the lesson is added to subtotal too (equipment.amount), and counts like the lesson.

managedBy is the rule that decides who answers: when it says instructor, the calendar and the requests are theirs and the API can read but not write; when it says school, the school — and so the API — writes the calendar and answers the requests, and the instructor watches. It is set from the roster in the panel, by a person, and cannot be changed through the API. Handing a calendar back to the instructor deletes the external blocks your system wrote on it.

When an instructor leaves the school, their bookings disappear from GET /bookings and their events stop, while what they already earned stays on your ledger. Neither that nor a managedBy change sends an event: diff GET /instructors on each sync.

unclaimed marks an instructor the school added in the panel without an account: nobody signs in as them, so they are always managedBy school and the school answers for them in everything, the chat included. When the person claims the profile with their own account, unclaimed turns false and the instructor's id changes to a permanent one: every path and the instructorId filter keep accepting the old id, the instructor carries it as previousId, and events from then on name the new one. No event announces it: diff GET /instructors on each sync and match previousId.

An instructor's availability is a list of blocks. A block is available, blocked or vacation, belongs to a resort the instructor teaches at, spans startTime to endTime (endTime may be 24:00), and is anchored either to a day of the week (dayOfWeek 0–6, Sunday first, optionally with since and until as the first and last dates it applies) or to one date — exactly one of the two. New available hours must fall between 07:00 and 21:00 on the resort's clock (a 422 outside_ski_day otherwise); blocked and vacation blocks may cover any time. Customers can only book inside available blocks that nothing else covers.

PUT /instructors/{id}/availability replaces the whole schedule — every resort, every block, up to 400 — with what you send, exactly like saving the calendar in the panel does. Ids are optional: the server assigns one to a block without one, keeps the ones you send, and refuses duplicates or the xb_ prefix of external blocks. External blocks (see below) are never touched by PUT and must not appear in it. A malformed block, an unknown resort, an overlap of the two anchors or a since later than the block's until is a 422 invalid_availability. Blocks that can no longer apply (a date that is over, a weekly block past its until) are dropped: PUT does not store them and GET does not return them. A date is over once it is over everywhere, at 12:00 UTC the next day.

GET …/availability/expanded does the arithmetic for you: for one resort and up to 62 days it returns, per day, the free ranges a customer could book and the busy ones, each busy range labelled booking (a confirmed lesson), pending (a paid request awaiting an answer) or external (a block from the API). It applies the buffer between lessons and the notice window the instructor set; it does not drop gaps shorter than their minimum lesson length, so a thirty-minute gap shows as free.

A lesson you sold outside Alpine Pal occupies the instructor. Register it as an external block and the slot disappears from the search, across every resort the instructor teaches at — a person cannot be in two valleys at once. Blocks need the school to manage the instructor (managedBy = school).

Each block carries your own externalRef. Sending the same reference again with the same date and hours is idempotent and returns 200 with the stored block, whatever resortId you pass; the same reference with different hours is a 409 external_ref_exists — delete and recreate. A block that overlaps a live booking is a 409 booking_conflict with the hours in the way and, when that booking is paid, its id and reference: that lesson is already sold on our side.

An instructor holds at most 400 external blocks from today on; one more is a 422 limit_reached. A block whose date is over (at 12:00 UTC the next day) goes by itself: GET /blocks no longer lists it, a DELETE of it is a 404 and it stops counting toward the 400.

Accepting a booking request checks the slot again: an external block on its hours, like a live booking or a group lesson there, makes the answer a 409 slot_conflict, and the school must reject the request or propose another time. On the unassigned seat, accepting re-checks nothing: its places were counted when the customer paid. Once your block is answered 201 the hour is yours: a checkout that was already under way on it is refunded when its payment tries to land, and reaches you as booking.expired.

A school can sell hours without saying who will teach them: the customer books and pays, and the school assigns an instructor whenever it likes — through the API, from the panel, or at the meeting point with whoever is free. On the API this is the school's own seat: it has a calendar, a price and an instant-confirmation switch of its own, it is not listed among /instructors, and its bookings arrive with unassigned: true and instructorId set to the seat (pool_…). It sells as many lessons at once as its calendar has places: an available block may carry capacity (up to 50; 1 when absent), counted at the block's resort minute by minute — a day's own blocks replace the weekly ones for the minutes they cover, and within either, overlapping blocks add up. A lesson needs a place for its whole length. The seat's group lessons take no places: they run alongside the private lessons and each other.

GET /unassigned shows the settings; PATCH /unassigned sets any of hourlyPrice, extraStudentPrice (0 or more; a negative one is a 422 invalid_price), extraStudentPer, durationPrices, seasonPrices, includedStudents, autoAcceptBookings and maximumStudents. The first PATCH creates the seat, and its calendar and block endpoints are 404 until then. There is no switch: active says whether the seat is on sale, which it is as soon as its hourly price is above the floor (or, selling formats, its formats and seasons are complete); it sells on the hours its calendar opens, so a school that does not want these lessons opens none. An active in a PATCH is ignored. Otherwise the seat's calendar works like an instructor's, at the school's resorts.

Fixed formats. Instead of hours, a school can sell its seat's private lessons as fixed formats, set up in the panel: up to 6 (morning, afternoon, full day or other, each with its start and end), and seasons — date ranges with a price per format, per lesson for the whole group. saleMode in GET /unassigned says which, and lessonFormats lists the formats and seasons (read-only on the API). While the seat sells formats, every private lesson on it is one of them: a format not priced in the season of a date is not sold that day, and a date outside every season sells nothing. A format needs a place free all along its hours, like any lesson on the seat, and is not bound by the 6-hour limit of lessons sold by the hour. Such a seat is on sale once its formats and seasons are complete, whatever its hourly price. Its bookings carry format (id and kind), subtotal is that day's price for the format, and propose-time moves one only to the same hours on a day that sells its format at the price paid (otherwise 409 format_fixed_time or format_price_differs). In the sandbox, POST /sandbox/bookings on the seat takes formatId and uses your school's formats.

Until the lesson is assigned the school is its instructor side: it answers the request, chats with the customer and agrees the meeting point. Once assigned, the booking is the instructor's like any other, and what the school may still do to it follows managedBy.

A group lesson is an event with seats that independent customers buy separately: a one-off (date) or a weekly series (dayOfWeek, optionally with since and until), with a capacity, a per-seat price for the whole class, a level, who it is for (audience: all, children or adults — a children's class may name a minAge and maxAge, and every student booking a seat must fit), a fixed meeting point and a minimum number of participants to run. An instructor's classes take their per-seat price from the instructor's own settings (groupClassesEnabled and groupPricePerStudent, writable through PATCH /instructors/{id}); only the unassigned seat names it at creation, and a price change re-stamps the active classes. Classes are published, handed to a teacher and cancelled from the panel — on the API they are read-only in v1 — and live on a roster instructor or on the unassigned seat.

GET /instructors/{id}/classes (and GET /unassigned/classes) list the active ones. GET …/classes/expanded?from&to resolves them to concrete dates with their seats taken, checkouts under their 10-minute hold included — at most 62 days per call. On an instructor's calendar a class's hours also read as busy in the availability's expanded view, and an external block on them is refused with a 409 booking_conflict: those hours are not yours to sell elsewhere. The unassigned seat is a team: its classes take nothing from its private places, run alongside them and alongside each other, and an external block never collides with them.

Every seat sold arrives through /bookings as an ordinary booking with a groupClassId, confirmed the moment it is paid (acceptedVia auto). propose-time and assign refuse a seat — the time belongs to the class and every other participant, and a class is handed to a teacher whole, from the panel. Cancelling a class (or one date of a series) refunds every seat in full and sends one booking.cancelled per seat; a class still under its minStudents 24 hours before an occurrence starts is called off the same way, with cancelledBy platform.

Only paid bookings reach the API: a booking exists for you from the instant its payment lands (paidAt), and a refunded one stays listed with its paymentStatus. A customer picks an instructor and a slot, pays, and the request lands with the instructor or the school. From then on it is either answered, or it expires unanswered and the customer is refunded.

The clock: the response deadline is 48 hours from payment, never later than the lesson's start; a proposal or a decline resets it (never past the earlier of the original and proposed starts); an hourly sweep expires what is overdue, so expiry can land up to an hour late. A confirmed lesson becomes upcoming 24 hours before it starts and in_progress while it runs. It completes when the customer confirms it, or 48 hours after its end by itself; completion releases your share. The customer may cancel free of charge until freeCancellationHours hours before the start: the booking's own window, the one your school's cancellation policy had when it was booked (48 by default), which it keeps whatever the policy says later.

About the customer you receive a short name (first name and initial), their preferred language and their message — enough to teach the lesson, and what our privacy policy promises them. Email, phone and any account identifier are never sent; the conversation with the customer stays in the chat on Alpine Pal, where the instructor is.

GET /bookings lists your instructors' paid bookings, oldest change first, with filters for status (a comma list), instructorId, from and to (lesson dates) and updatedSince (any ISO 8601 instant; inclusive). Pages are keyset-based on (updatedAt, id): follow nextCursor until it is null. The cursor is opaque and never expires, but it belongs to the filters it was made with — change them and start over; a made-up one is a 400.

The pattern for a nightly or hourly sync is the same one: remember the newest updatedAt you have seen and ask for everything since, exactly as you received it. Webhooks tell you the moment something changes; this endpoint is how you catch up after downtime. updatedAt also moves on changes that send no event — the lesson becoming upcoming or in_progress, a reminder sent — so a row can turn up in a sync with nothing visibly different.

Actions are open to the school on instructors it manages and on its own unassigned seat; on an instructor who manages themself the answer is 403 not_managed_by_school. Every action is a conditional update: if the booking is no longer in the state the action expects, the answer is 409 booking_state with the current state in details, and nothing changes. Repeating an action is therefore safe, and the way to confirm what happened is GET /bookings/{id}.

Two things are not here on purpose: marking a no-show and completing a lesson. Both move money on the strength of what happened on the slope, and both stay a human act in the panel.

Register an https URL and we POST every booking event to it — the same JSON the booking endpoints return, wrapped in an event. Up to 10 endpoints per school, each subscribed to some events or to all of them with "*". Register them from the panel or through the API; the panel shows the delivery log either way. The URL must be https, with a hostname that has a dot, no credentials or fragment, and not a private address or ours.

Events. booking.requested — a paid request arrived. booking.confirmed — accepted by the instructor or the school, confirmed automatically, or the customer accepted a proposed time: acceptedVia says which, and previousStatus is change_proposed in the last case. booking.time_proposed — another time was proposed to the customer. booking.rejected. booking.cancelled — cancelledBy is customer, instructor, school, or platform (the account behind the booking was deleted, or a group lesson was called off for missing its minimum). booking.expired — nobody answered in time. booking.completed — the lesson ended, no-shows included. booking.updated — anything else worth telling, with data.reason: proposal_declined, meeting_point_proposed, meeting_point_confirmed, dispute_opened, dispute_resolved, refund_settled (the money is back with the customer), refund_issued (by us), or instructor_assigned (previousInstructorId names the seat the lesson was on). ping is the test event, with an empty data; it is not a type you subscribe to. No event fires for upcoming, in_progress, roster or managedBy changes.

What to expect. Delivery is at least once: an answer that arrives after our 10-second timeout is counted as a failure and the event comes again, so treat the event id as the key and ignore repeats. Order is not guaranteed — retries and the sweep reorder events — so order by data.booking.updatedAt. Not every booking starts with booking.requested: one whose instructor has instant confirmation on (autoAcceptBookings) arrives directly as booking.confirmed, with previousStatus pending_instructor_approval. So create the booking in your system on the first event you see for its id, whatever its type. The payload is frozen when the event is made; a retry carries what was true then, and a later event, the newer state. An event can be lost if our attempt to record it fails; GET /bookings?updatedSince is the safety net. Every event carries sandbox: true or false. The log keeps deliveries for 30 days; a replay sends a past one again.

Every delivery is signed with the endpoint's secret: the X-AlpinePal-Signature header carries a timestamp and an HMAC-SHA256 of the timestamp, a dot and the raw body. Verify it before trusting anything, compare in constant time, and reject timestamps more than 5 minutes away from your clock. The secret is returned when you create the endpoint and by GET /webhooks, and can be rotated from the panel or with POST /webhooks/{id}/rotate-secret; the old one dies at once.

Answer with any 2xx within 10 seconds. Anything else — a 3xx included, since we do not follow redirects — is a failure: we retry after 5 minutes, 15 minutes, 1 hour, 4 hours, 12 hours and 24 hours, about 42 hours in all, each time with the same event id so you can deduplicate. An endpoint is switched off, and the school's managers told, only once a delivery has failed every retry with not a single delivery to it getting through in the meantime; a short outage does not switch it off, however many events are in flight. While it is off, new events are not queued for it (GET /bookings?updatedSince catches you up), and a pending delivery whose attempt falls due meanwhile is marked failed without being sent; retries that fall due after you switch it back on go out as usual. Replay the ones that failed. POST /webhooks/{id}/test queues a ping as an ordinary delivery, attempts it right away and reports how that attempt went: a failed ping is retried the same way, counts toward switching the endpoint off like any delivery, and on an endpoint that is off is marked failed without being sent. GET /webhooks/{id}/deliveries lists deliveries newest first, 50 by default and up to 100 with ?limit=, with their attempt count and without their bodies: an event has one delivery per endpoint, plus one for each replay, with the same event id.

Every school gets a sandbox twin the moment its owner mints a test key from the panel (Connections → Sandbox): a copy of the school with two made-up instructors — sandbox_ia_…, who answers requests by hand, and sandbox_ib_…, with instant confirmation on — and the unassigned-lessons seat, each with a 09:00–17:00 calendar every day at the school's resorts, 1 to 6 hours per lesson, up to 6 students, no buffer and no notice. Test keys start with ap_test_ and reach only the twin; live keys never do. Everything else is the same API: list the twin's instructors, write their calendars, register webhooks, answer requests, assign lessons.

What a customer does on the site, POST /sandbox/bookings does for you: it creates a paid booking for the instructor you name, with the same checks as a real one — published availability, no overlap — and no money involved. From there the real machinery runs, and the actions below stand in for the customer and the clock, so every event can be seen in minutes. No email leaves the sandbox, and nothing in it is ever public; every event it sends carries sandbox: true, and so does GET /me. POST /sandbox/reset empties it so a test suite can start clean.

Still out of reach in the sandbox: disputes, no-shows, a refund issued by us, a cancellation with cancelledBy platform, and the meeting point (its events come from the site). Sandbox bookings carry an empty studentLevels and a customer named Sandbox C. who reads the site in English.

The machine-readable description lives at https://alpinepal.com/api/v1/openapi.json — every path, method, parameter and schema above, in OpenAPI 3.1. Point a generator at it for a typed client, or import it into your HTTP tool to browse. It is served without authentication and cached for an hour.

This is v1. Within it we only add: new fields, new optional parameters, new event types, new endpoints. Your integration should ignore fields and events it does not know. Anything that would break an existing client goes to a v2 at a new base URL, with v1 kept running while you move.