Prepare an appointment

Prepare a SURA appointment in ONE read-only call. With patient identity and the ordered service, first checks existing appointments; if one matches, returns it and stops. Otherwise resolves patient, live service/area and professional names internally and reads availability, checking bounded date and professional alternatives while preserving explicit doctor/date/expiry constraints. Returns patient.primaryIps, actual service/professional, times and ready booking arguments. Use after the required document review, instead of chaining list_appointments, lookup_patient, list_services and find_availability. It NEVER books, cancels, changes an appointment or verifies the documents for you. Apply clinic eligibility to the result, offer up to three chronological verified options from options; nextDates are calendar hints that require an hour lookup, never confirmed slots. Use fromDate for later alternatives and preserve explicit date, doctor and time preferences. Propose an actual slot and obtain one confirmation before the separate book_appointment call. Existing-appointment-only questions still use list_appointments.

Scopes: any one of sura:appointments:read, sura:appointments:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: request body up to 32 KB, response up to 256 KB
CLI: arbol sura booking-options lookup · MCP tool: sura_booking_options_lookup

POST

https://api.getarbol.com/v1/sura/booking-options/lookup

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopes sura:appointments:read, sura:appointments:write. Get an API key.

Request body JSON required

documentNumber
string
required
Complete document number of the patient receiving care, from readable original evidence or their message. Normalize separators without changing digits. Request correction only for missing, illegible or conflicting identity; never guess digits.
documentType
ASI
or
CC
or
CD
or
CE
or
CN
or
DE
+16 more
required
Patient document type read legibly from the original or explicitly supplied. Ask only if unknown or genuinely conflicting; never infer it from age or number length.
serviceId
string
required
Exact service in the order or a previously returned service ID. Names are resolved internally against the live catalog; do not call list_services first or invent IDs. Preserve consultation/control and pediatric qualifiers.
areaId
optional
string | null
The areaId list_services returned beside that service. Pass it with an exact serviceId to skip a catalog lookup; omit it whenever you are naming the service in words.
date
optional
string | null
A day the person asked for, as YYYY-MM-DD. Its openings come first; when it has none, the openings nearest to it on either side are offered instead and requestedDateAvailable is false. Omit it for the soonest openings. Resolve relative dates like "mañana" against the clinic's own timezone before calling.
allowOtherProfessionals
optional
true
or
false
or
null
Whether other doctors of this service may be offered when the named doctor has no opening in the searched window. Defaults to true: the named doctor's openings come first, and only when that doctor has none are the other doctors' nearest openings returned, with requestedProfessionalAvailable false. Name the actual doctor of each option and obtain consent before booking. False keeps the named doctor as a strict filter.
fromDate
optional
string | null
Search from this day onward (YYYY-MM-DD), using the live calendar. Omit for today. Use date for a specific day.
timeFrom
optional
string | null
Earliest acceptable time, HH:mm, inclusive.
timeUntil
optional
string | null
Latest acceptable time, HH:mm, inclusive.
limit
optional
1
or
2
or
3
or
null
Number of chronological verified slots to return, defaults to 3. Proposals never hold capacity.
latestDate
optional
string | null
Explicit authorization expiry or latest date the person accepts, YYYY-MM-DD. Returned slots cannot exceed this date.
mode
optional
schedule
or
reschedule
or
null
Defaults to schedule: stop if a matching appointment exists. Use reschedule only when the person explicitly requests another date; returns alternatives without changing the existing appointment.
professional
optional
string | null
Doctor's name, or part of it, when the caller asked for someone specific. Use list_professionals to check the service's registered doctors independently of available slots; absence from an open-agenda selector does not mean the doctor does not exist. Omit it to see whoever has room soonest.
agentMode
optional
boolean
Set agentMode=true when calling this tool for an AI agent. The answer is concise Spanish text instead of JSON. Omit it for structured machine data. This changes presentation only, never authorization, consent or idempotency.

default: false
connectionId
optional
string
Which of the organization's SURA connections to run on, by its id. Optional while the organization has one; required when it has several.

maxLength: 128 · minLength: 1
channel
optional
voice
or
whatsapp
or
web
The channel the caller is waiting on, which sets how long it waits before an answer comes back pending, and puts a phone call's reads ahead of others. Defaults to web.

Returns

200

Successful operation.

JSON

success
true
required
data
required
One of the following:
SuraPendingResult
ai_hint
string
required
Spanish guidance for the model: what to do next.

ok
boolean
required
operationId
string
required
Pass it to operations.get, or repeat the identical call, to receive the result.

position
integer
required
Place in the connection's queue; 0 while it runs.

minimum: 0
retryAfterSeconds
integer
required
minimum: 1
status
string
required
SuraRefusal
ai_hint
string
required
Spanish guidance for the model: what to do next.

errorCode
string
required
Stable code, such as SLOT_TAKEN, PORTAL_BUSY or OPERATION_UNCONFIRMED.

ok
boolean
required
appointments
optional
array of
object
cancellable
boolean
required
False for an appointment at another clinic: read it out, but it cannot be cancelled here.

date
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

place
string
required
The clinic it is at. Say it only when the caller asks where.

professional
string
required
Say it only when the caller asks who.

service
string
required
What it is for: read it out with the date and the time.

serviceId
string
required
Internal; never read it out.

startsAt
string
required
The appointment's moment, with the clinic's offset: cancel it with this value.

format: date-time
time
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

areaId
optional
string
date
optional
string
error
optional
string
One English sentence for a developer.

month
optional
string
options
optional
array of
object
cancellable
boolean
required
False for an appointment at another clinic: read it out, but it cannot be cancelled here.

date
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

place
string
required
The clinic it is at. Say it only when the caller asks where.

professional
string
required
Say it only when the caller asks who.

service
string
required
What it is for: read it out with the date and the time.

serviceId
string
required
Internal; never read it out.

startsAt
string
required
The appointment's moment, with the clinic's offset: cancel it with this value.

format: date-time
time
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

place
optional
string
professionals
optional
array of
string
service
optional
string | null
serviceId
optional
string
services
optional
array of
string
times
optional
array of
string
today
optional
string
SuraPreparationPatientNotFound
ai_hint
string
required
Spanish guidance for the model: what to do next.

documentNumber
string
required
documentType
string
required
found
boolean
required
ok
boolean
required
status
string
required
SuraPatientNotFound
ai_hint
string
required
Spanish guidance for the model: what to do next.

documentNumber
string
required
documentType
string
required
found
boolean
required
ok
boolean
required
SuraPreparationExistingAppointment
ai_hint
string
required
Spanish guidance for the model: what to do next.

appointments
array of
object
required
The patient's pending appointments of the requested service.

cancellable
boolean
required
False for an appointment at another clinic: read it out, but it cannot be cancelled here.

date
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

place
string
required
The clinic it is at. Say it only when the caller asks where.

professional
string
required
Say it only when the caller asks who.

service
string
required
What it is for: read it out with the date and the time.

serviceId
string
required
Internal; never read it out.

startsAt
string
required
The appointment's moment, with the clinic's offset: cancel it with this value.

format: date-time
time
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

ok
boolean
required
status
string
required
SuraPreparationAvailable
ai_hint
string
required
Spanish guidance for the model: what to do next.

date
string | null
required
The day shown, YYYY-MM-DD.

ok
boolean
required
otherDates
array of
string
required
Other days that month with room.

otherProfessionals
array of
string
required
Other doctors who see this service.

patient
object
required
documentNumber
string
required
documentType
string
required
fullName
string
required
primaryIps
string | null
required
The primary-care IPS SURA has assigned to the patient.

plan
string | null
required
The coverage the portal itself applied.

professional
string | null
required
service
string | null
required
times
array of
string
required
The hours that may be booked that day, HH:MM.

appointments
array of
object
required
The patient's pending appointments of the requested service.

cancellable
boolean
required
False for an appointment at another clinic: read it out, but it cannot be cancelled here.

date
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

place
string
required
The clinic it is at. Say it only when the caller asks where.

professional
string
required
Say it only when the caller asks who.

service
string
required
What it is for: read it out with the date and the time.

serviceId
string
required
Internal; never read it out.

startsAt
string
required
The appointment's moment, with the clinic's offset: cancel it with this value.

format: date-time
time
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

booking
object
required
date
deprecated
string | null
required
Deprecated: use startsAt. Answered until 2027-01-28.

documentNumber
string
required
documentType
ASI
or
CC
or
CD
or
CE
or
CN
or
DE
+16 more
required
Patient document type read legibly from the original or explicitly supplied. Ask only if unknown or genuinely conflicting; never infer it from age or number length.

professional
string | null
required
serviceId
string
required
areaId
optional
string
startsAt
optional
string
The first opening's moment, with the clinic's offset.

format: date-time
time
deprecated
string
Deprecated: use startsAt. Answered until 2027-01-28.

searched
array of
object
required
date
string | null
required
professional
string | null
required
status
string
required
options
optional
array of
object
date
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

time
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

startsAt
string
required
The opening's moment, with the clinic's offset: book it with appointments.create.

format: date-time
professional
string
required
nextDates
optional
array of
object
Known available calendar days, not verified hours and not reservations.

date
string
required
professional
string
required
searchComplete
optional
boolean
False when the bounded search stopped before establishing the requested nearest options.

requestedProfessionalAvailable
optional
boolean
Present when a professional was named: true when the options are that doctor's, false when that doctor had no opening in the searched window and any options are other doctors' of the same service.

requestedDateAvailable
optional
boolean
Present when a date was given: true when an option falls on that day, false when it had none and any options are the nearest days to it.

SuraPreparationNoSlots
ai_hint
string
required
Spanish guidance for the model: what to do next.

date
string | null
required
The day shown, YYYY-MM-DD.

ok
boolean
required
otherDates
array of
string
required
Other days that month with room.

otherProfessionals
array of
string
required
Other doctors who see this service.

patient
object
required
documentNumber
string
required
documentType
string
required
fullName
string
required
primaryIps
string | null
required
The primary-care IPS SURA has assigned to the patient.

plan
string | null
required
The coverage the portal itself applied.

professional
string | null
required
service
string | null
required
times
array of
string
required
The hours that may be booked that day, HH:MM.

appointments
array of
object
required
The patient's pending appointments of the requested service.

cancellable
boolean
required
False for an appointment at another clinic: read it out, but it cannot be cancelled here.

date
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

place
string
required
The clinic it is at. Say it only when the caller asks where.

professional
string
required
Say it only when the caller asks who.

service
string
required
What it is for: read it out with the date and the time.

serviceId
string
required
Internal; never read it out.

startsAt
string
required
The appointment's moment, with the clinic's offset: cancel it with this value.

format: date-time
time
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

searched
array of
object
required
date
string | null
required
professional
string | null
required
status
string
required
options
optional
array of
object
date
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

time
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.

startsAt
string
required
The opening's moment, with the clinic's offset: book it with appointments.create.

format: date-time
professional
string
required
nextDates
optional
array of
object
Known available calendar days, not verified hours and not reservations.

date
string
required
professional
string
required
searchComplete
optional
boolean
False when the bounded search stopped before establishing the requested nearest options.

requestedProfessionalAvailable
optional
boolean
Present when a professional was named: true when the options are that doctor's, false when that doctor had no opening in the searched window and any options are other doctors' of the same service.

requestedDateAvailable
optional
boolean
Present when a date was given: true when an option falls on that day, false when it had none and any options are the nearest days to it.
}
error
unknown
required
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

400

INVALID_INPUT: The request does not match the published schema.

JSON

success
false
required
data
unknown
required
error
object
required
The request does not match the published schema.
- code
  INVALID_INPUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  issues
  optional
  array of
  object
  path
  string
  required
  RFC 6901 JSON Pointer to the refused field; empty for the whole input.
  
  maxLength: 256
  message
  string
  required
  maxLength: 256
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

401

UNAUTHORIZED: A valid access token is required.

JSON

success
false
required
data
unknown
required
error
object
required
A valid access token is required.
- code
  UNAUTHORIZED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

403

FORBIDDEN: The token does not authorize this operation.

JSON

success
false
required
data
unknown
required
error
object
required
The token does not authorize this operation.
- code
  FORBIDDEN
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

404

CONNECTION_NOT_FOUND: The organization has no such connection.

JSON

success
false
required
data
unknown
required
error
object
required
The organization has no such connection.
- code
  CONNECTION_NOT_FOUND
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

409

PORTAL_SESSION_CONFLICT: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team.
CONNECTION_NOT_CONFIGURED: The organization has no SURA connection that can run this operation.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
SuraPortalSessionConflictFailure
PORTAL_SESSION_CONFLICT
code
PORTAL_SESSION_CONFLICT
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.

SuraConnectionNotConfiguredFailure
CONNECTION_NOT_CONFIGURED
code
CONNECTION_NOT_CONFIGURED
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

success
false
required
data
unknown
required
error
object
required
The request exceeds the allowed size.
- code
  REQUEST_TOO_LARGE
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

success
false
required
data
unknown
required
error
object
required
The request content type is not supported.
- code
  UNSUPPORTED_MEDIA_TYPE
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

success
false
required
data
unknown
required
error
object
required
The request rate limit was exceeded. Try again later.
- code
  RATE_LIMITED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

success
false
required
data
unknown
required
error
object
required
The service could not complete the operation.
- code
  INTERNAL_ERROR
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
PORTAL_CREDENTIALS_REJECTED: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team.
PORTAL_UNAVAILABLE: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
OutcomeUnknownFailure
OUTCOME_UNKNOWN
code
OUTCOME_UNKNOWN
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

SuraPortalCredentialsRejectedFailure
PORTAL_CREDENTIALS_REJECTED
code
PORTAL_CREDENTIALS_REJECTED
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

SuraPortalUnavailableFailure
PORTAL_UNAVAILABLE
code
PORTAL_UNAVAILABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.

JSON

success
false
required
data
unknown
required
error
object
required
The upstream service could not complete the request.
- code
  UPSTREAM_UNAVAILABLE
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

success
false
required
data
unknown
required
error
object
required
The upstream service did not respond before its deadline.
- code
  UPSTREAM_TIMEOUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string