Get an operation

Get the result of an earlier call that answered status "pending", by its operationId. SURA's portal does one thing at a time per account, so a call may wait its turn; it keeps running even if you stop waiting. Call this after retryAfterSeconds. It waits briefly and answers pending again while the operation is still running. Repeating the original call with the same arguments also returns the same operation.

Scopes: any one of sura:appointments:read, sura:appointments:write, sura:affiliations:read
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: response up to 256 KB
CLI: arbol sura operations get · MCP tool: sura_operations_get

GET

https://api.getarbol.com/v1/sura/operations/{operationId}

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, sura:affiliations:read. Get an API key.

Path parameters

operationId
string
required
The operationId of the pending answer, exactly as it was returned.

Query parameters

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
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
SuraPatientFound
ai_hint
string
required
Spanish guidance for the model: what to do next.

found
boolean
required
ok
boolean
required
patient
object
required
age
integer | null
required
birthDate
string | null
required
city
string | null
required
documentNumber
string
required
documentType
object
required
id
string
required
name
string
required
entitlementStatus
string | null
required
firstSurname
string | null
required
fullName
string
required
givenNames
string | null
required
plan
string | null
required
The coverage the portal assigns itself.

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

secondSurname
string | null
required
sex
string | null
required
SuraServicePage
data
array of
object
required
Items admitted by this resource contract within the verified organization.

areaId
string
required
areaName
string
required
id
string
required
name
string
required
object
string
required
Discriminator for a resource list response.

pageInfo
object
required
Opaque navigation cursors for this page’s stable keyset order.

hasNextPage
boolean
required
Whether a later page exists in the current ordering.

hasPreviousPage
boolean
required
Whether an earlier page exists in the current ordering.

nextCursor
string | null
required
Opaque cursor for the next page, or null when there is none.

previousCursor
string | null
required
Opaque cursor for the previous page, or null when there is none.

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.

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.

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

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

ok
boolean
required
patient
string
required
The patient's full name.

plan
string | null
required
professional
string | null
required
service
string | null
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.

SuraAppointmentPage
data
array of
object
required
Items admitted by this resource contract within the verified organization.

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.

object
string
required
Discriminator for a resource list response.

pageInfo
object
required
Opaque navigation cursors for this page’s stable keyset order.

hasNextPage
boolean
required
Whether a later page exists in the current ordering.

hasPreviousPage
boolean
required
Whether an earlier page exists in the current ordering.

nextCursor
string | null
required
Opaque cursor for the next page, or null when there is none.

previousCursor
string | null
required
Opaque cursor for the previous page, or null when there is none.

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.

SuraAffiliation
active
boolean
required
affiliateType
string
required
ai_hint
string
required
Spanish guidance for the model: what to do next.

documentNumber
string
required
documentType
string
required
incomeGroup
string
required
ok
boolean
required
outcome
string
required
plans
string
required
providerCode
string
required
providerStatus
string
required
SuraNoContract
active
null
required
ai_hint
string
required
Spanish guidance for the model: what to do next.

documentNumber
string
required
documentType
string
required
ok
boolean
required
outcome
string
required
providerCode
string
required
providerStatus
string
required
SuraAuthorization
ai_hint
string
required
Spanish guidance for the model: what to do next.

authorizationNumber
string
required
documentNumber
string
required
documentType
string
required
expiresOn
string
required
YYYY/MM/DD, as SURA writes it.

fees
object
required
affiliateReportedPaidAmount
number | null
required
chargeType
string
required
COPAGO, CUOTA MODERADORA or COTIZANTE EXENTO.

copayMaximumAmount
null
required
copayPercentage
number | null
required
currency
string
required
fixedFeeAmount
number | null
required
institutionReportedAmount
number | null
required
outstandingBalance
null
required
incomeGroup
string
required
issuedOn
string
required
YYYY/MM/DD, as SURA writes it.

issuerCode
string
required
ok
boolean
required
outcome
string
required
providerCode
string
required
providerStatus
string
required
SuraCopayHistory
accumulatedCopayAmount
number
required
Historical total for the year, not a balance to pay.

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

currency
string
required
documentNumber
string
required
documentType
string
required
entries
array of
object
required
authorizationNumber
string
required
copayAmount
number | null
required
feeCopayAmount
number | null
required
issuedOn
string
required
YYYY/MM/DD, as SURA writes it.

planComplementaryAmount
number | null
required
providerStatus
string
required
ok
boolean
required
outcome
string
required
year
string
required
SuraNoCopayHistory
accumulatedCopayAmount
null
required
ai_hint
string
required
Spanish guidance for the model: what to do next.

currency
string
required
documentNumber
string
required
documentType
string
required
entries
array of
object
required
authorizationNumber
string
required
copayAmount
number | null
required
feeCopayAmount
number | null
required
issuedOn
string
required
YYYY/MM/DD, as SURA writes it.

planComplementaryAmount
number | null
required
providerStatus
string
required
ok
boolean
required
outcome
string
required
providerCode
string
required
year
string
required
}
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

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