Skip to main content
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, chain create with confirm:

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 - application/json
_id
string
required

Id de la cita

branch
object
required
dates
object
required
status
string
required

pending | confirmed | cancelled | …

appointment_number
number

Correlativo legible de la cita

service
object
professional
object
customer
object
appointment_type
string

online | in-person

payment_status
string

Estado del pago

notes
string
price
number
currency
string

Moneda ISO 4217

paid
boolean
cancelled_at
string<date-time>
cancellation_reason
string
created_at
string<date-time>
updated_at
string<date-time>