Create booking

Book the quoted slot

POST/v1/bookings

curl -X POST 'https://www.yovamos.com/v1/bookings' \
  -H "Authorization: Bearer $VAMOS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteId": "qte_8fK2mQ4xN7vRjT1aZc9LpA",
  "customer": {
    "name": "Sam Rivera",
    "email": "sam@example.com"
  },
  "consent": {
    "humanConfirmed": true,
    "statement": "Yes, book it."
  }
}'

{
  "id": "bkg_bk000001",
  "status": "confirmed",
  "business": {
    "id": "biz_1v8g0yh11jl8ti",
    "name": "The Spot Barbershop",
    "timezone": "America/Los_Angeles"
  },
  "service": {
    "id": "svc_1wwvyo2007ynbx",
    "name": "Haircut"
  },
  "staff": {
    "id": "stf_0ngvtdm17z44qf",
    "name": "Marcus"
  },
  "startsAt": "2027-01-12T17:00:00Z",
  "endsAt": "2027-01-12T17:45:00Z",
  "local": "Tue, Jan 12 · 9:00–9:45 AM PST",
  "durationMinutes": 45,
  "partySize": 1,
  "price": {
    "amountMinor": 3500,
    "currency": "USD",
    "display": "$35.00"
  },
  "customer": {
    "name": "Sam Rivera",
    "email": "sam@example.com"
  },
  "source": "Dots",
  "consent": {
    "statement": "Yes, book it.",
    "at": "2027-01-11T21:40:12.000Z"
  },
  "manageUrl": "https://www.yovamos.com/booking/manage?booking=bkg_bk000001",
  "createdAt": "2027-01-11T21:40:12.000Z",
  "next": [
    "Tell the customer the booking is confirmed."
  ],
  "untrusted": [
    "business.name",
    "service.name",
    "staff.name",
    "customer.name",
    "consent.statement"
  ],
  "manageToken": "mu8_4y8WOdIm_zK99LM3BBwWq8RdowYV"
}

Headers

AuthorizationBearer tokenRequired
Your app key. Authentication
idempotency-keystring
Your key for this booking attempt: 1-128 printable ASCII characters, no spaces (a UUID or your own order id). Repeating the exact same request with the same key returns the same booking.

Body

quoteIdstringRequired
Short-lived quote id from create_quote (prefix qte_). Copy it exactly. It expires; request a new quote if it does.
customerCustomerInputRequired
customer.namestring (up to 120 characters)Required
Full name as the customer wants it on the booking.
customer.emailstring (up to 254 characters)Required
Email address (plain ASCII, e.g. sam@example.com).
customer.phonestring
Phone number, digits with optional leading + and separators.
consentConsentInputRequired
consent.humanConfirmedbooleanRequired
Set true ONLY after the human customer read what they are agreeing to (quote.summary to book; the new time and price to move a booking) and said yes. Never assume or invent consent.
consent.statementstring (up to 500 characters)Required
The customer's own reply agreeing (to the booking, or to the move), copied word for word. Required: it is kept as the consent record. Never write it yourself.
notesstring (up to 500 characters)
Anything the customer wants the business to know. Optional.
partnerRefstring (up to 64 characters)
Your own reference for this booking (conversation id, order id). It is echoed back on the booking and in webhooks.

Responses

201
A booking: its status, time, price, the customer's consent record and what to do next.
Booking
404
No such id, or it is not visible to this key.
NotFound
409
The price is no longer the one quoted: show the new one and get a fresh yes. | The way this is confirmed (instantly or by the business) is no longer the one quoted: show the new quote and get a fresh yes. | The slot was taken or can no longer be booked: alternatives lists nearby openings. | This Idempotency-Key, or this quote, already produced a booking for a different request.
410
The quote's hold has lapsed: create a new quote.
QuoteExpired
422
The customer's explicit consent is missing: stop and ask the human.
ConsentRequired

Search documentation

Businesses

Services

Staff

Resources

Slots

Quotes

Bookings

ScheduleOperator key

System

Guidance for apps and assistants

Headers

Body

Responses