tiempoAPI reference
v1 · 2026-10-04API keysDashboard
API reference

Bookings

Time held on one or more resources. A booking starts pending (a hold that expires after 15 minutes by default) and becomes confirmed when you confirm it. Placing a booking locks its resources first, so when two requests race for the same time exactly one wins.

Create a booking

POST/v1/bookings

Places a booking: pending by default, or confirmed straight away with status "confirmed". All segments are placed together or not at all. Give a segment resources (candidates in order of preference) instead of resource for “anyone available”. A 409 booking_conflict lists the reason for each segment.

Send the business’s id in Tiempo-Account.

Body parameters

  • segmentsarray of objectsrequired

    The time to hold: one entry per resource and period. Segments can be on different resources and needn’t touch.

    • resourcestring

      A resource id.

    • resourcesarray of strings

      Candidate resource ids in your order of preference; Tiempo takes the first that fits.

    • starttimestamprequired

      An ISO-8601 instant.

    • endtimestamprequired

      An ISO-8601 instant, after start.

    • quantityinteger

      Units of capacity to take. Defaults to 1 (for blocks, the whole capacity).

    • locationstring

      A location id.

    • buffer_before_minutesinteger

      Minutes the resource is also held before the time (travel, setup), 0–1440. On a booking segment it overrides the resource’s default; the appointment’s start and end don’t change.

    • buffer_after_minutesinteger

      Minutes the resource is also held after the time (cleanup, turnaround), 0–1440. On a booking segment it overrides the resource’s default. Buffers must fit in working hours and can’t overlap blocks or other bookings.

  • statusstring

    pending (a hold) or confirmed.

  • expires_attimestamp

    When a hold lapses. Defaults to 15 minutes; at most your platform’s longest hold ahead, 24 hours unless an owner or admin changes it in the dashboard (up to 7 days).

  • seatsinteger

    Makes the booking a session that attendees take seats in.

  • conflict_policystring

    reject (default) refuses time that isn’t free or isn’t working hours. capacity_only ignores working hours, overrides and blocks (staff booking a client in after hours) but still never overlaps another booking. allow places it anyway (a deliberate overbook) and flags it.

  • replacesstring

    A booking this one replaces. Its time doesn’t count against the new booking, and it’s cancelled when the new one is confirmed.

  • metadatamap

    Up to 50 keys of your own (strings, keys up to 40 characters, values up to 500). Returned on every read and webhook. On update, an empty string removes a key.

Returns

The booking. Sends booking.created (and booking.confirmed if created confirmed).

List bookings

GET/v1/bookings

Bookings overlapping a window, newest made first or, with order=start, earliest first. Give the window as local dates (from_date and to_date, inclusive, in the business’s timezone unless you pass timezone), so “next Thursday” or “the week of 18 December” needs no timezone maths; or as instants with from and to. conflicted=true finds the bookings a rota change broke.

Send the business’s id in Tiempo-Account.

Query parameters

  • statusstring

    Only objects with this status.

  • resourcestring

    Only those involving this resource. On the calendar, repeat it for several.

  • locationstring

    Only those at this location.

  • seriesstring

    Only this series’ occurrences.

  • fromtimestamp

    Only those ending after this instant.

  • totimestamp

    Only those starting before this instant.

  • from_datedate

    From this local date (YYYY-MM-DD), inclusive.

  • to_datedate

    To this local date (YYYY-MM-DD), inclusive.

  • timezonestring

    The timezone of from_date and to_date. Defaults to the business’s (for the calendar, the location’s first).

  • conflictedboolean

    true for bookings a rota, block or capacity change no longer fits.

  • orderstring

    created (default): newest made first. start: earliest first, by start time.

  • limitinteger

    1 to 100. Defaults to 20.

  • starting_afterstring

    An object id from the previous page; returns the page after it.

  • ending_beforestring

    An object id; returns the page before it.

  • metadata[key]string

    Only objects whose metadata has this key and value. Repeat for several.

Retrieve a booking

GET/v1/bookings/{id}

Send the business’s id in Tiempo-Account.

Path parameters

  • idstringrequired

    The object’s id.

Update a booking

POST/v1/bookings/{id}

Extends a hold (expires_at, up to your platform’s longest hold: 24 hours unless you’ve changed it), changes seats on a session, or updates metadata.

Send the business’s id in Tiempo-Account.

Path parameters

  • idstringrequired

    The object’s id.

Body parameters

  • expires_attimestamp

    When a hold lapses. Defaults to 15 minutes; at most your platform’s longest hold ahead, 24 hours unless an owner or admin changes it in the dashboard (up to 7 days).

  • seatsinteger

    Makes the booking a session that attendees take seats in.

  • metadatamap

    Up to 50 keys of your own (strings, keys up to 40 characters, values up to 500). Returned on every read and webhook. On update, an empty string removes a key.

Confirm a booking

POST/v1/bookings/{id}/confirm

Turns a hold into a kept booking, usually once the customer has paid. An expired hold can’t be confirmed (409); its time may already be gone.

Send the business’s id in Tiempo-Account.

Path parameters

  • idstringrequired

    The object’s id.

Returns

The confirmed booking. Sends booking.confirmed. This is when it counts towards usage.

Reschedule a booking

POST/v1/bookings/{id}/reschedule

Moves a booking to new segments in place: same id, and its own current time doesn’t count against it. Sends booking.rescheduled with the previous segments.

Send the business’s id in Tiempo-Account.

Path parameters

  • idstringrequired

    The object’s id.

Body parameters

  • segmentsarray of objectsrequired

    The time to hold: one entry per resource and period. Segments can be on different resources and needn’t touch.

    • resourcestring

      A resource id.

    • resourcesarray of strings

      Candidate resource ids in your order of preference; Tiempo takes the first that fits.

    • starttimestamprequired

      An ISO-8601 instant.

    • endtimestamprequired

      An ISO-8601 instant, after start.

    • quantityinteger

      Units of capacity to take. Defaults to 1 (for blocks, the whole capacity).

    • locationstring

      A location id.

    • buffer_before_minutesinteger

      Minutes the resource is also held before the time (travel, setup), 0–1440. On a booking segment it overrides the resource’s default; the appointment’s start and end don’t change.

    • buffer_after_minutesinteger

      Minutes the resource is also held after the time (cleanup, turnaround), 0–1440. On a booking segment it overrides the resource’s default. Buffers must fit in working hours and can’t overlap blocks or other bookings.

  • conflict_policystring

    reject (default) refuses time that isn’t free or isn’t working hours. capacity_only ignores working hours, overrides and blocks (staff booking a client in after hours) but still never overlaps another booking. allow places it anyway (a deliberate overbook) and flags it.

Cancel a booking

POST/v1/bookings/{id}/cancel

Frees the time straight away. Cancelling a session cancels its attendees.

Send the business’s id in Tiempo-Account.

Path parameters

  • idstringrequired

    The object’s id.

Body parameters

  • reasonstring

    Your note, kept on the object and its webhook.

Complete a booking

POST/v1/bookings/{id}/complete

Records that it happened, or that it’s been paid for: allowed before it starts. The time stays taken until the booking ends; only cancelling frees it.

Send the business’s id in Tiempo-Account.

Path parameters

  • idstringrequired

    The object’s id.

Mark a booking as a no-show

POST/v1/bookings/{id}/no_show

Records that the customer didn’t come. Only once the booking has started (409 booking_not_started before). The time stays taken.

Send the business’s id in Tiempo-Account.

Path parameters

  • idstringrequired

    The object’s id.