Find free slots

The free slots of one service under one contract at a cost centre, from a day on, read from every professional's agenda (or the one named), each with the reference visoft.appointments.create takes. A professional whose agenda SIIPS did not answer is failed:true: their slots are unknown, never none. Never cached. This read never books anything.

Scopes: any one of visoft:appointments:read, visoft: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 64 KB, response up to 1 MB
CLI: arbol visoft availability lookup · MCP tool: visoft_availability_lookup

POST

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

Request body JSON required

contractCode
string
required
The contract, by the code visoft.contracts.list answers.

maxLength: 40 · minLength: 1 · pattern: ^[A-Za-z0-9_-]+$
serviceCode
string
required
The service, by the code a contract's services answer ("CUPS-890208").

maxLength: 60 · minLength: 3 · pattern: ^[A-Za-z0-9]+-[A-Za-z0-9._-]+$
from
string
required
The day the search starts, in the clinic's time (YYYY-MM-DD): SIIPS answers each professional's free slots from that day on.

pattern: ^\d{4}-\d{2}-\d{2}$
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]+$
agencyCode
optional
string
One of the clinic's cost centres, as visoft.clinic.get lists them. Optional when the clinic has a default one.

pattern: ^\d{3}$
professionalId
optional
string
One professional's id, as visoft.professionals.list answers it: only their agenda.

maxLength: 40 · minLength: 1 · pattern: ^[A-Za-z0-9_-]+$
refreshProfessionals
optional
boolean
Read the professional directory again instead of its one-hour cache.
concurrency
optional
integer
How many agendas are read from SIIPS at once (5 by default).

maximum: 10 · minimum: 1

Returns

200

Successful operation.

JSON

success
true
required
data
object
required
- from
  string
  required
  The day the search started, in the clinic: YYYY-MM-DD.
- professionals
  array of
  object
  required
  Every professional of the service at the cost centre (or the one asked for), in the directory's order, each with their free slots. Never cached: read for this call.
  
  professional
  object
  required
  id
  string
  required
  The professional's SIIPS id. Empty only in an availability answer of an agenda SIIPS lists without its professionals.
  
  name
  string
  required
  Their name, without the specialty SIIPS appends.
  
  label
  string
  required
  Their name as SIIPS labels it.
  
  specialty
  string
  required
  The specialty SIIPS appends to the label; empty when none.
  
  failed
  boolean
  required
  Whether SIIPS failed to answer this professional's agenda: their slots are unknown, never none.
  
  slots
  array of
  object
  required
  Their free slots, in the order SIIPS lists them.
  
  reference
  string
  required
  The free slot's SIIPS key, as visoft.availability.lookup answered it: pass it unchanged to visoft.appointments.create.
  
  maxLength: 200 · minLength: 7
  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.
  
  professionalName
  string
  required
  The professional, as SIIPS names them.
  
  specialty
  string
  required
  The specialty SIIPS shows on the agenda.
  
  agencyCode
  string
  required
  The cost centre the slot is at.
  
  scheduleId
  string
  required
  The agenda block the slot belongs to.
  
  slotNumber
  string
  required
  The slot's position in its agenda block.
  
  subCostCenter
  string
  required
  The sub cost centre of the agenda.
  
  status
  string
  required
  SIIPS's status of the slot.
  
  purpose
  string
  required
  The purpose SIIPS shows on the agenda.
}
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.
PROFESSIONAL_NOT_FOUND: No professional with that id attends the service at the clinic's cost centre.

JSON

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

VisoftProfessionalNotFoundFailure
PROFESSIONAL_NOT_FOUND
code
PROFESSIONAL_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.

JSON

success
false
required
data
unknown
required
error
object
required
The organization has no active Visoft connection for this call; an administrator connects Visoft in Account.
- 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.
}

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.

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