Crear una cita
Appointments
POST /v1/scheduling/appointments
Create an appointment in pending state with embedded customer data. Keebai generates the id (UUID).
POST
Crear una cita
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
Required scope
scheduling:appointments:create
Headers
Body
Example request
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: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, chaincreate with confirm:
Booking with deferred confirmation (customer must confirm)
Leaving the appointment inpending 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
Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.
Body
application/json
Fecha (YYYY-MM-DD)
Hora inicio (HH:mm)
Hora fin (HH:mm). Si se omite, scheduling la calcula desde la duración del servicio.
Response
201 - application/json
Id de la cita
pending | confirmed | cancelled | …
Correlativo legible de la cita
online | in-person
Estado del pago
Moneda ISO 4217