Patient Management
Manage patients within your client organization.
Authentication
Requires a Client token with scopes:
patient:read— For GET endpointspatient:write— For POST/PUT/DELETE endpoints
Endpoints
List Patients
http
GET /ext/latest/patients
Authorization: Bearer {token}Query Parameters:
externalId(optional) — Filter by external IDfirstName(optional) — Filter by first namelastName(optional) — Filter by last namedob(optional) — Filter by date of birth (YYYY-MM-DD)email(optional) — Filter by emaillimit(optional) — Page size (default: 10, max: 100)offset(optional) — Page offset (default: 0)
Response:
json
{
"data": [
{
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"firstName": "Gerry",
"lastName": "North",
"dob": "1980-11-14",
"gender": "Male",
"email": "gerry@example.com",
"phone": "5658888883",
"externalId": "144012243566593",
"patientStatus": "Active"
}
],
"limit": 10,
"offset": 0,
"hasMore": true
}Get Patient
http
GET /ext/latest/patients/{patientId}
Authorization: Bearer {token}Create Patient
http
POST /ext/latest/patients
Content-Type: application/json
Authorization: Bearer {token}Request Body:
json
{
"firstName": "Gerry",
"lastName": "North",
"dob": "1980-11-14",
"gender": "Male",
"email": "gerry@example.com",
"phone": "5658888883",
"externalId": "144012243566593",
"altAddresses": [
{
"address1": "7 Delegate Street",
"city": "Springfield",
"state": "MA",
"zip": "20002",
"current": true
}
],
"altTelecoms": [
{
"type": "MC",
"value": "5658888883"
},
{
"type": "HP",
"value": "5623331212"
}
],
"altNames": [
{
"type": "maiden",
"value": "Smith"
}
]
}Response (201 Created):
json
{
"data": { ... }
}Update Patient
http
PUT /ext/latest/patients/{patientId}
Content-Type: application/json
Authorization: Bearer {token}Request Body: (all fields optional)
json
{
"firstName": "Gerald",
"email": "gerald.north@example.com",
"phone": "5658888884"
}Delete Patient
http
DELETE /ext/latest/patients/{patientId}
Authorization: Bearer {token}Response (204 No Content): (no body)
Batch Upsert Patients
Upsert up to 100 patients in a single call. The API matches existing patients by:
- Exact
externalIdmatch (when provided) - Fuzzy demographic match (requires
dob+genderexact match, scores on name/address/telecom) - No match → create new patient
http
POST /ext/latest/patients/batch
Content-Type: application/json
Authorization: Bearer {token}Request Body:
json
{
"patients": [
{
"firstName": "Gerry",
"lastName": "North",
"dob": "1980-11-14",
"gender": "Male",
"externalId": "EXT-1"
},
{
"firstName": "Lee",
"lastName": "South",
"dob": "1990-06-01",
"gender": "Female",
"email": "lee@example.com"
}
]
}Response:
json
{
"data": [
{
"index": 0,
"status": "updated",
"matchType": "externalId",
"patientId": "c7836b96-..."
},
{
"index": 1,
"status": "created",
"patientId": "8b2e1d94-..."
}
],
"summary": {
"total": 2,
"created": 1,
"updated": 1,
"error": 0
}
}Batch Operations
Use batch endpoints to reduce API calls and rate limit pressure. Partial success is supported — one bad item doesn't fail the entire batch.
Patient Object Fields
| Field | Type | Create | Update | Description |
|---|---|---|---|---|
patientId | string | — | — | System-generated UUID (read-only) |
clientId | string | — | — | Owning client ID (read-only) |
firstName | string | required | optional | First name |
lastName | string | required | optional | Last name |
middleName | string | optional | optional | Middle name (nullable) |
dob | string | required | optional | Date of birth (YYYY-MM-DD) |
gender | string | required | optional | Sex (e.g., Male, Female) |
email | string | optional | optional | Email address (nullable) |
phone | string | optional | optional | Primary phone (nullable) |
faxNumber | string | optional | optional | Fax number (nullable) |
salutation | string | optional | optional | Salutation (nullable) |
mrn | string | optional | optional | Medical record number (nullable) |
externalId | string | optional | optional | External system ID (nullable) |
patientStatus | string | — | — | Active or Inactive (read-only) |
altAddresses | array | optional | optional | Array of addresses (see below) |
altTelecoms | array | optional | optional | Array of telecom methods (see below) |
altNames | array | optional | optional | Array of alternate names (see below) |
Address Object
| Field | Type | Required | Description |
|---|---|---|---|
address1 | string | yes | Street address |
address2 | string | no | Suite/unit |
city | string | yes | City |
state | string | no | State |
zip | string | no | ZIP code |
current | boolean | no | Whether this is the current address |
Telecom Object
| Field | Type | Required | Description |
|---|---|---|---|
type | string | yes | MC=Mobile, HP=Home, WP=Work |
value | string | yes | Phone number or contact value |
AltName Object
| Field | Type | Required | Description |
|---|---|---|---|
type | string | yes | maiden, firstname, lastname, or middlename |
value | string | yes | The alternate name value |
Examples
Node.js
javascript
async function createPatient(token, patientData) {
const response = await fetch('https://api.vivliohealth.io/ext/latest/patients', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`
},
body: JSON.stringify(patientData)
});
return response.json();
}
async function batchUpsertPatients(token, patients) {
const response = await fetch('https://api.vivliohealth.io/ext/latest/patients/batch', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`
},
body: JSON.stringify({ patients })
});
return response.json();
}Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or invalid fields |
| 401 | FORBIDDEN | Missing authentication or invalid token |
| 403 | FORBIDDEN | Insufficient scopes |
| 404 | RESOURCE_NOT_FOUND | Patient not found |
| 409 | RESOURCE_EXISTS | Duplicate MRN or email |
| 422 | INVALID_REFERENCE | Referenced client does not exist |
