Correct a patient's details

Change only the fields named in the call; every other field keeps its stored value (gender identity and sexual orientation included). The change is verified by a fresh read before it is answered. PATIENT_NOT_FOUND: SIIPS has no such patient. PATIENT_NOT_SAVED: SIIPS answered but the fresh read did not show the change. A correction 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 correct · MCP tool: visoft_patients_correct

POST

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

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

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]+$
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}$
firstName1
optional
string
First given name.

maxLength: 60
firstName2
optional
string
Second given name.

maxLength: 60
lastName1
optional
string
First surname.

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
address
optional
string
Home address.

maxLength: 200
birthDate
optional
string
Birth date, YYYY-MM-DD.

pattern: ^\d{4}-\d{2}-\d{2}$
sex
optional
M
or
F
Sex at birth: M or F.

Returns

200

Successful operation.

JSON

success
true
required
data
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.
PATIENT_NOT_FOUND: SIIPS has no patient with that document.

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.

VisoftPatientNotFoundFailure
PATIENT_NOT_FOUND
code
PATIENT_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.
}