Cancel an appointment

Cancel one appointment the patient already has, identified by its moment: startsAt, exactly as list_appointments answered it (or the former date and time). Confirm with the caller which appointment, in their own words, before calling. Only appointments at this clinic can be cancelled here. ok:true with cancelled:true means it is gone; anything else means it is not, so never tell the caller it was cancelled without that.

Scope: sura:appointments:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: writes; not idempotent: check the outcome before you retry
Limits: request body up to 32 KB, response up to 256 KB
CLI: arbol sura appointments cancel · MCP tool: sura_appointments_cancel

POST

https://api.getarbol.com/v1/sura/appointments/cancel

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope 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.
reason
optional
patient_request
or
reschedule
or
provider_request
or
null
Why it is being cancelled. Defaults to patient_request. Use reschedule when the caller wants a different time and you are about to book another one.
serviceId
optional
string | null
Only needed when the patient has more than one appointment at that exact date and time, which the tool will tell you.
startsAt
optional
string
The appointment's moment, as an RFC 3339 instant with its offset, exactly as an answer gave it in startsAt (for example "2026-11-04T17:00:00-05:00"). Send it in place of the former date and time; sent beside them, they must name the same moment.

format: date-time
date
deprecated
string
Deprecated: use startsAt. Answered until 2027-01-28.
time
deprecated
string
Deprecated: use startsAt. Answered until 2027-01-28.
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
SuraCancelledAppointment
ai_hint
string
required
Spanish guidance for the model: what to do next.

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

ok
boolean
required
service
string
required
startsAt
string
required
The appointment's moment, with the clinic's offset.

format: date-time
time
deprecated
string
required
Deprecated: use startsAt. Answered until 2027-01-28.
}
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