Book an appointment

Find the service. Search for the name the patient used with agenda.bookingOfferings.list:

curl --get https://api.getarbol.com/v1/agenda/booking-offerings \
  --data-urlencode "q=neurología" --data-urlencode "limit=3" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

Each offering in data.data carries its id, its serviceId, its sites and what the service asks of the patient: service.bookingChecklist to check against what you know, service.patientInstructions, and service.eligibility, such as { "minAgeYears": 18, "maxAgeYears": null }. With an age rule, you’ll need the patient’s date of birth.

Check the requirements. agenda.bookingRequirements.get answers the intake fields, document types and payers; payerQuery leaves out unrelated payers:

curl --get https://api.getarbol.com/v1/agenda/booking-requirements \
  --data-urlencode "payerQuery=Example Health Plan" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

In data.fields, built-in fields such as phone and payer are off, optional or required, and document is optional or required; data.customFields adds the organization’s own; data.documentTypes lists the document codes, such as CC; and each payer in data.payers has a bookingPolicy, open or staff_only. Collect each required value you don’t have yet. If the payer’s policy is staff_only, don’t book: put the patient on the waitlist.

Find a slot. agenda.nearestBookingSlots.list answers the earliest times across every agenda that offers the service:

curl --get https://api.getarbol.com/v1/agenda/nearest-booking-slots \
  --data-urlencode "serviceId=svc_00000000-0000-4000-8000-000000000001" \
  --data-urlencode "timezone=America/Bogota" --data-urlencode "limit=3" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

{
  "startsAt": "2026-11-05T09:00:00-05:00",
  "timezone": "America/Bogota",
  "slotToken": "EXAMPLE_SLOT_TOKEN_0001"
}

That’s the first slot in data.data, abridged: each also has its endsAt, offeringId and resourceIds. Offer the times to the patient in the slot’s timezone. An empty list means there’s no opening as far ahead as the service can be booked: offer the waitlist.

Book it once the patient confirms the time. Send the slotToken unchanged to agenda.bookings.create, with the patient and the intake the clinic requires:

curl https://api.getarbol.com/v1/agenda/bookings \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "slotToken": "EXAMPLE_SLOT_TOKEN_0001",
    "patient": { "name": "Example Patient", "documentNumber": "1234567890", "documentType": "CC" },
    "patientBirthDate": "1990-01-01",
    "intake": { "phone": "+57 300 000 0000", "entity": "Example Health Plan" }
  }'

The answer is the appointment; keep its id, which rescheduling and cancelling take. Abridged, from data:

{
  "id": "eng_00000000-0000-4000-8000-000000000005",
  "startsAt": "2026-11-05T09:00:00-05:00",
  "guidance": {
    "attendedBy": ["Dr. Example"],
    "patientInstructions": "Bring your medical order and arrive 15 minutes early.",
    "location": { "name": "Example Clinic North", "address": "Calle 00 # 00-00", "city": "Bogotá" }
  },
  "slip": { "url": "https://example.com/EXAMPLE-slip.pdf", "expiresAt": "2026-10-30T16:00:00Z" }
}

Confirm it to the patient. Tell them the time and what guidance says: the instructions, who attends, and the site with its address. Download the slip while its link works, within the hour, and send them the PDF file rather than the link:

curl --fail --output appointment-slip.pdf "$SLIP_URL"

Here SLIP_URL holds data.slip.url; the link carries no credential. agenda.bookings.get reads the appointment again later, with its guidance and slip. Setting a status such as confirmed is the clinic’s: staff do it with agenda.appointments.changeStatus, which accepts only people.