Look up a patient

SIIPS's record of the patient with that document number, and, when history asks for it, the patient's agenda (each appointment with the reference visoft.appointments.cancel takes) and admissions. found:false is an answer, not a failure. The record is cached for five minutes (refresh reads SIIPS again); the agenda is read for every call.

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 patients lookup · MCP tool: visoft_patients_lookup

POST

https://api.getarbol.com/v1/visoft/patients/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

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

pattern: ^[A-Za-z0-9]{1,20}$
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]+$
history
optional
none
or
current
or
all
none (the default): the record alone. current: also the patient's current agenda and admissions. all: past appointments too.
refresh
optional
boolean
Read SIIPS again instead of the connection's cache (contracts 12 h, services 6 h, professionals 1 h, a patient 5 min).

Returns

200

Successful operation.

JSON

success
true
required
data
object
required
- found
  boolean
  required
  Whether SIIPS has a patient with that document.
- patient
  required
  The record; null when not found.
  
  One of the following:
  VisoftPatient
  documentType
  string
  required
  The document's type, as SIIPS codes it (CC, TI, RC…). Empty when SIIPS holds none.
  
  documentNumber
  string
  required
  The patient's document number.
  
  firstName1
  string
  required
  First given name. Empty when SIIPS holds none.
  
  firstName2
  string
  required
  Second given name. Empty when SIIPS holds none.
  
  lastName1
  string
  required
  First surname. Empty when SIIPS holds none.
  
  lastName2
  string
  required
  Second surname. Empty when SIIPS holds none.
  
  fullName
  string
  required
  Given names and surnames, in that order, as SIIPS spells them.
  
  birthDate
  string
  required
  Birth date. YYYY-MM-DD, or empty.
  
  pattern: ^(\d{4}-\d{2}-\d{2})?$
  sex
  string
  required
  Sex at birth: M or F. Empty when SIIPS holds none.
  
  genderIdentity
  string
  required
  Gender identity. Empty when SIIPS holds none.
  
  sexualOrientation
  string
  required
  Sexual orientation. Empty when SIIPS holds none.
  
  maritalStatus
  string
  required
  Marital status. Empty when SIIPS holds none.
  
  phoneMobile
  string
  required
  Mobile phone. Empty when SIIPS holds none.
  
  phoneOffice
  string
  required
  Office phone. Empty when SIIPS holds none.
  
  email
  string
  required
  Email address. Empty when SIIPS holds none.
  
  address
  string
  required
  Home address. Empty when SIIPS holds none.
  
  zone
  string
  required
  U (urban) or R (rural). Empty when SIIPS holds none.
  
  country
  string
  required
  Country of residence (COL…). Empty when SIIPS holds none.
  
  departmentCode
  string
  required
  DANE department code of residence. Empty when SIIPS holds none.
  
  departmentName
  string
  required
  Department of residence. Empty when SIIPS holds none.
  
  municipalityCode
  string
  required
  DANE municipality code of residence. Empty when SIIPS holds none.
  
  cityName
  string
  required
  City of residence. Empty when SIIPS holds none.
  
  neighborhoodCode
  string
  required
  Neighborhood code. Empty when SIIPS holds none.
  
  affiliateType
  string
  required
  Affiliation type (C: cotizante…). Empty when SIIPS holds none.
  
  stratum
  string
  required
  Socioeconomic stratum, 1 to 6. Empty when SIIPS holds none.
  
  status
  string
  required
  Vital status (Vivo…). Empty when SIIPS holds none.
  
  populationCode
  string
  required
  Population code. Empty when SIIPS holds none.
  
  populationGroupCode
  string
  required
  Population group code. Empty when SIIPS holds none.
  
  professionCode
  string
  required
  Profession code. Empty when SIIPS holds none.
  
  educationCode
  string
  required
  Education code. Empty when SIIPS holds none.
  
  occupation
  string
  required
  Occupation. Empty when SIIPS holds none.
  
  ethnicity
  string
  required
  Ethnicity. Empty when SIIPS holds none.
  
  disabilityPhysical
  string
  required
  S when SIIPS records a physical disability. Empty when SIIPS holds none.
  
  disabilityMental
  string
  required
  S when SIIPS records a mental disability. Empty when SIIPS holds none.
  
  disabilityPsychiatric
  string
  required
  S when SIIPS records a psychiatric disability. Empty when SIIPS holds none.
  
  chronicHypertension
  string
  required
  S when SIIPS records hypertension. Empty when SIIPS holds none.
  
  chronicHypertensionSince
  string
  required
  Since when. Empty when SIIPS holds none.
  
  chronicDiabetes
  string
  required
  S when SIIPS records diabetes. Empty when SIIPS holds none.
  
  chronicDiabetesSince
  string
  required
  Since when. Empty when SIIPS holds none.
  
  chronicRenal
  string
  required
  S when SIIPS records chronic kidney disease. Empty when SIIPS holds none.
  
  chronicRenalSince
  string
  required
  Since when. Empty when SIIPS holds none.
  
  latitude
  string
  required
  Latitude of the address. Empty when SIIPS holds none.
  
  longitude
  string
  required
  Longitude of the address. Empty when SIIPS holds none.
  
  providerMessage
  string
  required
  SIIPS's own note on the record. Empty when SIIPS holds none.
  
  null
- history
  required
  The agenda and admissions, when history asked for them and the patient was found.
  
  One of the following:
  VisoftPatientHistory
  appointments
  array of
  object
  required
  The patient's agenda, as SIIPS lists it: never cached, read for this call.
  
  reference
  string
  required
  The appointment's SIIPS key, opaque: pass it unchanged to visoft.appointments.cancel. Empty when SIIPS offers no action on it.
  
  scheduleId
  string
  required
  The agenda block the appointment belongs to.
  
  agencyCode
  string
  required
  The cost centre it is at.
  
  contractCode
  string
  required
  The contract it was booked under.
  
  specialty
  string
  required
  The specialty, as SIIPS names it.
  
  service
  string
  required
  The service, as SIIPS lists it on the agenda.
  
  professionalId
  string
  required
  The professional's SIIPS id; empty when SIIPS omits it.
  
  professionalName
  string
  required
  The professional, as SIIPS names them.
  
  visitType
  string
  required
  How SIIPS classified the visit (1ra Vez, Control…).
  
  startsAt
  string | null
  required
  When it starts, in the clinic's offset; null when SIIPS's row carries no readable day and hour.
  
  format: date-time
  admissionNumber
  string
  required
  The admission it was attended under; empty before one.
  
  attended
  string
  required
  SIIPS's attendance mark.
  
  purpose
  string
  required
  The purpose SIIPS records.
  
  resource
  string
  required
  The resource it holds.
  
  subCostCenter
  string
  required
  The sub cost centre.
  
  tag
  string
  required
  SIIPS's tag on the row.
  
  web
  string
  required
  Whether it was booked from the web, as SIIPS marks it.
  
  phone
  string
  required
  The phone SIIPS shows on the row.
  
  patientSummary
  string
  required
  The patient summary SIIPS shows on the row.
  
  admissions
  array of
  object
  required
  The patient's admissions, as SIIPS lists them.
  
  admissionNumber
  string
  required
  The admission's number.
  
  agencyCode
  string
  required
  The cost centre it was at.
  
  date
  string
  required
  The day it was recorded, as SIIPS writes it.
  
  professionalId
  string
  required
  The professional's SIIPS id.
  
  specialty
  string
  required
  The specialty, as SIIPS names it.
  
  status
  string
  required
  SIIPS's status of the admission.
  
  null
}
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.

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.

JSON

success
false
required
data
unknown
required
error
object
required
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.
- 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.
}
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.
}