Find availability

Find the free appointment times for one patient and one service. With no date it answers with the soonest day that has room; with a date it answers for that day. times[] are the hours you may book, otherDates[] are other days that month with room, and otherProfessionals[] are the other doctors who see this service. Offer two or three times, never the whole list.

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 availability lookup · MCP tool: sura_availability_lookup

POST

https://api.getarbol.com/v1/sura/availability/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
What the appointment is for: either an id from list_services or the service's own name, in the caller's words ("neurología", "control"). A name that matches more than one service is answered with the choices, so you can ask which one instead of guessing.
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 to look at, as YYYY-MM-DD. Omit it for the soonest day with room. Resolve relative dates like "mañana" against the clinic's own timezone before calling.
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
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
SuraAvailability
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.
}
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