Booking lifecycle

Required fields

The minimum fields each endpoint needs, by vertical.

Treat every field shown in a vertical's example as required for that vertical. Omitting any of them causes the booking to fail or produce unexpected results; the examples are the contract, not a suggestion.

Checked on every booking

These are refused with a 400 before anything is created, so a mistake costs nothing:

RuleRefusal

venue_id from a search

provider required: set the 'provider' field or use a venue_id with a known provider mapping

A customer with at least a name, email or phone

customer name or contact required

Dining: customer.name, party_size 1–20, and a datetime in the future

validation failed: … (one message per field, e.g. "datetime: must be in the future")

OpenTable: a first and last name in customer.name

missing_last_name

The real guest's details, not placeholders: no example.com / .test emails, no US numbers in a 555 exchange, no names like "Customer Name" or "Test User"

placeholder_customer (the field is named in the message)

With an availability_id: the datetime it was offered at

slot_not_offered

Fitness (Mindbody): signing in

Mindbody identifies a member by their email. A new email gets a new Mindbody account. An email that already has an account signs in with a code Mindbody emails to that address: the booking returns requires_action with an otp next action, and you submit the code as otp_code to /continue. If you know the account's password you can send it in metadata.password instead; it is optional.

An account that signs in with Google or Apple is switched to email sign-in so the emailed code can be used; the link to Google or Apple is removed once the code is entered. If Mindbody does not offer that switch, the booking fails with mindbody_social_login. If an existing account is not offered a code sign-in at all, it fails with account_exists.