Register a patient

Register a patient in the clinic's SIIPS at one of its cost centres, then read the record back to prove it saved. A patient SIIPS already has is answered with alreadyExisted:true and nothing written. PATIENT_NOT_SAVED: SIIPS answered but a fresh read did not show the record; read before trying again. A registration whose outcome is unknown answers OUTCOME_UNKNOWN and is never repeated automatically.

Scope: visoft:patients: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 64 KB, response up to 1 MB
CLI: arbol visoft patients create · MCP tool: visoft_patients_create

POST

https://api.getarbol.com/v1/visoft/patients

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:patients:write. Get an API key.

Request body JSON required

documentType
CC
or
TI
or
RC
or
AS
or
CD
or
CE
+8 more
required
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).
documentNumber
string
required
The patient's document number: letters and digits only, without dots, spaces or hyphens.

pattern: ^[A-Za-z0-9]{1,20}$
firstName1
string
required
First given name.

maxLength: 60 · minLength: 1
lastName1
string
required
First surname.

maxLength: 60 · minLength: 1
birthDate
string
required
Birth date, YYYY-MM-DD.

pattern: ^\d{4}-\d{2}-\d{2}$
sex
M
or
F
required
Sex at birth: M or F.
address
string
required
Home address.

maxLength: 200 · minLength: 1 · pattern: \S
country
string
required
Country of residence, ISO 3166 alpha-3 (COL).

pattern: ^[A-Z]{3}$
departmentCode
string
required
DANE department code of residence.

pattern: ^\d{1,2}$
municipalityCode
string
required
DANE municipality code of residence.

pattern: ^\d{3,5}$
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}$
firstName2
optional
string
Second given name.

maxLength: 60
lastName2
optional
string
Second surname.

maxLength: 60
phoneMobile
optional
string
Mobile phone.

maxLength: 30
phoneOffice
optional
string
Office phone.

maxLength: 30
email
optional
string
Email address.

maxLength: 120
affiliateType
optional
string
Affiliation type; C (cotizante) by default.

maxLength: 2
maritalStatus
optional
string
Marital status; Soltero by default.

maxLength: 30
zone
optional
U
or
R
U (urban, the default) or R.
stratum
optional
string
Socioeconomic stratum; 1 by default.

maxLength: 2
status
optional
string
Vital status; Vivo by default.

maxLength: 20
educationCode
optional
string
Education code; 01 by default.

maxLength: 4
populationCode
optional
string
Population code; 06 by default.

maxLength: 4
populationGroupCode
optional
string
Population group code; 99 by default.

maxLength: 4
professionCode
optional
string
Profession code.

maxLength: 10
occupation
optional
string
Occupation.

maxLength: 100
neighborhoodCode
optional
string
Neighborhood code; 0 by default.

maxLength: 10
genderIdentity
optional
string
Gender identity; SinDatos by default.

maxLength: 30
sexualOrientation
optional
string
Sexual orientation; SinDatos by default.

maxLength: 30
chronicDiabetes
optional
boolean
Whether the patient has diabetes.
chronicHypertension
optional
boolean
Whether the patient has hypertension.
chronicRenal
optional
boolean
Whether the patient has chronic kidney disease.
disabilityMental
optional
boolean
Whether the patient has a mental disability.
disabilityPhysical
optional
boolean
Whether the patient has a physical disability.
disabilityPsychiatric
optional
boolean
Whether the patient has a psychiatric disability.

Returns

201

Successful operation.

JSON

success
true
required
data
object
required
- created
  boolean
  required
  Whether this call registered the patient.
- alreadyExisted
  boolean
  required
  Whether SIIPS already had the patient: nothing was written, and the stored record answers.
- patient
  object
  required
  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.
}
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.
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.
PATIENT_NOT_SAVED: SIIPS answered the registration or correction, but a fresh read did not show it saved. Nothing is retried; read the patient before trying again.

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.

VisoftPatientNotSavedFailure
PATIENT_NOT_SAVED
code
PATIENT_NOT_SAVED
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.
}

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