Cancel an appointment

Cancel one of the patient's appointments, by the reference a fresh visoft.patients.lookup answered in history.appointments. The patient's agenda is read again right before the write, and an appointment no longer in it is APPOINTMENT_NOT_CANCELLABLE. minimumNoticeMinutes refuses one that starts sooner (CANCEL_NOTICE_REQUIRED). CANCELLATION_REFUSED: SIIPS did not confirm it (data.message says why). A cancellation whose outcome is unknown answers OUTCOME_UNKNOWN: read the patient's agenda before anything else, never repeat it blindly.

Scope: visoft:appointments:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: deletes; not idempotent: check the outcome before you retry
Limits: request body up to 64 KB, response up to 1 MB
CLI: arbol visoft appointments cancel · MCP tool: visoft_appointments_cancel

POST

https://api.getarbol.com/v1/visoft/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 visoft:appointments:write. Get an API key.

Request body JSON required

documentNumber
string
required
The patient's document number: letters and digits only, without dots, spaces or hyphens.

pattern: ^[A-Za-z0-9]{1,20}$
reference
string
required
The appointment's reference, exactly as visoft.patients.lookup answered it in history.appointments.

maxLength: 400 · minLength: 3
connectionId
optional
string
The connection to run on. Optional when the organization has one Visoft connection; required when it has several. Another organization's connection is CONNECTION_NOT_FOUND.

maxLength: 68 · minLength: 5 · pattern: ^con_[0-9A-Za-z]+$
documentType
optional
CC
or
TI
or
RC
or
AS
or
CD
or
CE
+8 more
The document's type, as SIIPS codes it: CC (Cédula de Ciudadanía), TI (Tarjeta de Identidad), RC (Registro Civil), AS (Adulto sin Identificación), CD (Carné Diplomático), CE (Cédula de Extranjería), DE (Documento de Extranjero), CN (Certificado de Nacido Vivo), MS (Menor sin Identificación), SC (Salvoconducto), PE (Permiso Especial de Permanencia), PT (Permiso de Protección Temporal), SI (Sin Identificación), PA (Pasaporte). The patient's own by default.
minimumNoticeMinutes
optional
integer
Refuse (CANCEL_NOTICE_REQUIRED) when the appointment starts sooner than this: checked against SIIPS's own day and hour, before reading and again right before the write.

maximum: 10080 · minimum: 1
reasonCode
optional
string
SIIPS's cancellation cause; 06 (Petición cliente) by default.

pattern: ^\d{2}$
observation
optional
string
What SIIPS records with the cancellation; "Peticion cliente" by default.

maxLength: 200 · minLength: 1

Returns

200

Successful operation.

JSON

success
true
required
data
object
required
- scheduleId
  string
  required
  The agenda block the appointment was in.
- startsAt
  string
  required
  The moment, as an RFC 3339 instant written in the clinic's own offset (for example "2026-11-04T08:50:00-05:00"), so its first ten characters are the clinic's day and the next eight its hour.
  
  format: date-time
- professionalId
  string
  required
  The professional's SIIPS id.
}
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.
}

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.
}

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.
}

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.
}

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.
}

409

CONNECTION_NOT_CONFIGURED: The organization has no active Visoft connection for this call; an administrator connects Visoft in Account.
APPOINTMENT_NOT_CANCELLABLE: The appointment is no longer cancellable in the patient's current agenda; read the patient again. Nothing was cancelled.
CANCEL_NOTICE_REQUIRED: The appointment starts sooner than the minimum notice the call asked for. Nothing was cancelled.
CANCEL_TIME_UNVERIFIED: The appointment's day and hour could not be verified against the minimum notice. Nothing was cancelled.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
VisoftConnectionNotConfiguredFailure
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.

VisoftAppointmentNotCancellableFailure
APPOINTMENT_NOT_CANCELLABLE
code
APPOINTMENT_NOT_CANCELLABLE
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.

VisoftCancelNoticeRequiredFailure
CANCEL_NOTICE_REQUIRED
code
CANCEL_NOTICE_REQUIRED
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.

VisoftCancelTimeUnverifiedFailure
CANCEL_TIME_UNVERIFIED
code
CANCEL_TIME_UNVERIFIED
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.
}

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.
}

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.
}

422

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.
AGENCY_NOT_SERVED: The cost centre is not one of the connection's clinic: use one visoft.clinic.get lists.
APPOINTMENT_REFERENCE_INVALID: The reference is not one a patient's appointments answered. Nothing was cancelled.
CANCELLATION_REFUSED: SIIPS did not confirm the cancellation (data.message says why). Nothing is retried.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
VisoftCredentialsRejectedFailure
CREDENTIALS_REJECTED
code
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.

VisoftAgencyNotServedFailure
AGENCY_NOT_SERVED
code
AGENCY_NOT_SERVED
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.

VisoftAppointmentReferenceInvalidFailure
APPOINTMENT_REFERENCE_INVALID
code
APPOINTMENT_REFERENCE_INVALID
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.

VisoftCancellationRefusedFailure
CANCELLATION_REFUSED
code
CANCELLATION_REFUSED
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
message
string
required
SIIPS's own message, without markup, as its form answered it. Never a credential; read it, never show it to a patient as it is.

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

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.
}

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.
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
PROVIDER_UNAVAILABLE: The clinical system did not answer or could not complete the request.

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.

VisoftProviderUnavailableFailure
PROVIDER_UNAVAILABLE
code
PROVIDER_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.
}

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.
}

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.
}