Scheduling a booking

This guide walks through the complete flow to schedule an appointment using the CitaPro API. You will use the endpoints in this order: services, locations, professionals, availability, client (create or find), and finally create the booking.

Step 1: Get services

List the business services so the user can choose one. The service will determine duration and price.

GET /v1/services

Example response (relevant fields):

{
  "total": 10,
  "items": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "name": "Corte de cabello",
      "duration": 60,
      "price": 50.0,
      "status": "active"
    }
  ]
}

Save the chosen serviceId and duration (in minutes) for later steps.

See Services reference for the full schema.

Step 2: Get locations (branches)

List locations (sucursales) where the service is offered. The user will pick where they want the appointment.

GET /v1/locations

Example response (relevant fields):

{
  "total": 3,
  "items": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Sede Principal",
      "address": "Av. Amazonas N36-152",
      "status": "active"
    }
  ]
}

Save the chosen locationId for availability and booking.

See Locations reference for the full schema.

Step 3: Get professionals (optional)

You can list professionals to let the user choose a specific one, or skip this and let availability return all available professionals.

GET /v1/people

You can filter by locationId so only professionals assigned to the chosen location are shown. The response includes id, firstname, lastname, email, status, etc.

Save the chosen personId if the user selects a professional; otherwise omit it when checking availability.

See People reference for the full schema.

Step 4: Check availability

Get available time slots for the selected service and location (and optionally professional) within a date range.

GET /v1/bookings/availability?locationId={locationId}&serviceId={serviceId}&startDate=2026-03-10&endDate=2026-03-17

Parameter	Required	Description
`locationId`	Yes	UUID of the location
`serviceId`	Yes	UUID of the service
`startDate`	No	Start date `YYYY-MM-DD` (default: today)
`endDate`	No	End date `YYYY-MM-DD` (default: startDate + 30 days, max 30 days)
`professionalId`	No	Filter by a specific professional UUID

Example response:

{
  "days": ["2026-03-10", "2026-03-11", "2026-03-12"],
  "professionals": [
    { "id": "990e8400-e29b-41d4-a716-446655440004", "name": "María García" }
  ],
  "slots": [
    {
      "startTime": "2026-03-10 09:00:00",
      "endTime": "2026-03-10 10:00:00",
      "professionals": [
        { "id": "990e8400-e29b-41d4-a716-446655440004", "name": "María García" }
      ]
    }
  ],
  "limitExceeded": false
}

The user picks a slot. Use that slot’s startTime and endTime for the booking (convert to ISO 8601 if needed, e.g. 2026-03-10T09:00:00Z). If they chose a professional, use that slot’s professionals[].id as personId when creating the booking.

See Bookings – Check availability for details.

Step 5: Create or get the client

You need a clientId to create the booking. Either find an existing client (e.g. by email) or create one.

Option A: Find existing client

List clients filtered by email (or phone) and use the first match if any:

GET /v1/clients?filters[0][field]=email&filters[0][operator]==&filters[0][value]=juan@example.com

If items is not empty, use items[0].id as clientId.

Option B: Create a new client

If no client exists, create one:

POST /v1/clients
Content-Type: application/json

Body (minimum required fields):

{
  "firstname": "Juan",
  "lastname": "Pérez",
  "email": "juan@example.com",
  "phone": "+593991234568"
}

Response: 201 Created with { "id": "660e8400-e29b-41d4-a716-446655440001" }. Use this id as clientId.

See Clients reference for all fields (e.g. docType, birthdate, address, customFields).

Step 6: Create the booking

Create the appointment with the data collected in the previous steps.

POST /v1/bookings
Content-Type: application/json

Body:

Field	Value
`startTime`	Start of the chosen slot (ISO 8601, e.g. `2026-03-10T09:00:00Z`)
`endTime`	End of the chosen slot (ISO 8601, e.g. `2026-03-10T10:00:00Z`)
`status`	e.g. `confirmed` or `pending`
`amount`	Service price (e.g. from the service object)
`clientId`	Client UUID from step 5
`locationId`	Location UUID from step 2
`serviceId`	Service UUID from step 1
`personId`	(Optional) Professional UUID from the chosen slot
`notifyClient`	(Optional) `true` to send confirmation to the client

Example:

{
  "startTime": "2026-03-10T09:00:00Z",
  "endTime": "2026-03-10T10:00:00Z",
  "status": "confirmed",
  "amount": 50.00,
  "clientId": "660e8400-e29b-41d4-a716-446655440001",
  "locationId": "770e8400-e29b-41d4-a716-446655440002",
  "serviceId": "880e8400-e29b-41d4-a716-446655440003",
  "personId": "990e8400-e29b-41d4-a716-446655440004",
  "notifyClient": true
}

Response: 201 Created with { "id": "cc0e8400-e29b-41d4-a716-446655440007" } — the new booking ID.

See Bookings – Create booking for the full schema and validation rules.

Summary

Step	Endpoint	Purpose
1	`GET /services`	Choose service (id, duration, price)
2	`GET /locations`	Choose location/branch
3	`GET /people`	(Optional) Choose professional
4	`GET /bookings/availability`	Get available slots
5	`GET /clients` or `POST /clients`	Get or create client
6	`POST /bookings`	Create the appointment

Handle validation errors (422) and rate limiting (429) in your client for a robust integration.