Skip to main content
POST
/
v1
/
scheduling
/
appointments
Crear una cita
curl --request POST \
  --url https://api.keebai.com/v1/scheduling/appointments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "branch_id": "<string>",
  "service_id": "<string>",
  "date": "<string>",
  "start_time": "<string>",
  "customer": {
    "name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "phone": "<string>"
  },
  "professional_id": "<string>",
  "end_time": "<string>",
  "notes": "<string>",
  "price": 123,
  "currency": "<string>"
}
'
Creates a new appointment. The appointment lands in pending state and must be confirmed explicitly with POST /appointments/:id/confirm. The _id is generated by Keebai (UUID v4) and returned in the response. The customer (customer) is embedded in the body — you don’t need to create a Customer beforehand. If the service defines duration_minutes, you can omit end_time and Keebai will compute it from start_time + duration.

​
Endpoint

POST https://api.keebai.com/v1/scheduling/appointments

​
Required scope

scheduling:appointments:create

​
Headers

HeaderRequiredValue
AuthorizationYesBearer kbai_pk_<token>
Content-TypeYesapplication/json

​
Body

FieldTypeRequiredDescription
branch_idstringYesBranch where the appointment is booked.
service_idstringYesService to deliver.
professional_idstringNoAssigned professional. If omitted, scheduling picks an available one.
datestringYesDate (YYYY-MM-DD).
start_timestringYesStart time (HH:mm) in the branch’s tz.
end_timestringNoEnd time (HH:mm). If omitted, computed from the service’s duration.
customer.namestringYesCustomer first name.
customer.last_namestringNoLast name.
customer.emailstringNoValid email.
customer.phonestringNoPhone number.
notesstringNoInternal notes (max 1000 characters).
pricenumberNoAppointment-specific fee. Overrides the service price.
currencystringNoISO 4217 currency (CLP, USD, etc.).

​
Example request

curl -X POST https://api.keebai.com/v1/scheduling/appointments \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_id": "65a1f2b3c4d5e6f7a8b9c0d1",
    "service_id": "65b1c2d3e4f5a6b7c8d9e0f1",
    "professional_id": "66c1d2e3f4a5b6c7d8e9f0a1",
    "date": "2026-05-02",
    "start_time": "10:00",
    "customer": {
      "name": "Juan",
      "last_name": "Pérez",
      "phone": "+56912345678",
      "email": "juan@example.com"
    },
    "notes": "Primera consulta"
  }'

​
Response

​
201 Created

Returns the freshly created appointment with its _id and status: "pending". Shape identical to the body of GET /appointments/:id.

​
400 Bad Request

Invalid body (bad date/time formats, missing fields, malformed email).

​
409 Conflict

The requested slot is already taken or conflicts with another appointment or service rule. The body includes the reason: 
{
  "error": {
    "code": "SLOT_NOT_AVAILABLE",
    "message": "El profesional no tiene disponibilidad para el horario solicitado."
  }
}

​
401 Unauthorized · 403 Forbidden

Same semantics as the rest of the public API.

​
Common patterns

​
Single-shot booking with immediate confirmation

If your integration validates the appointment in the same step, chain create with confirm: 
appointment = requests.post(
    "https://api.keebai.com/v1/scheduling/appointments",
    headers=auth_headers,
    json=payload,
    timeout=10,
).json()

requests.post(
    f"https://api.keebai.com/v1/scheduling/appointments/{appointment['_id']}/confirm",
    headers=auth_headers,
    timeout=10,
).raise_for_status()

​
Booking with deferred confirmation (customer must confirm)

Leaving the appointment in pending lets you implement “confirm your appointment within the next 2 hours” flows (typical when there’s an external payment or a human-in-the-loop validation).

Authorizations

​
Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Body

application/json
​
branch_id
string
required
​
service_id
string
required
​
date
string
required

Fecha (YYYY-MM-DD)

​
start_time
string
required

Hora inicio (HH:mm)

​
customer
object
required
​
professional_id
string
​
end_time
string

Hora fin (HH:mm). Si se omite, scheduling la calcula desde la duración del servicio.

​
notes
string
​
price
number
​
currency
string

Response

201

Cita creada