Skip to content

Patient Management ​

Manage patients within your client organization.

Authentication ​

Requires a Client token with scopes:

  • patient:read — For GET endpoints
  • patient:write — For POST/PUT/DELETE endpoints

Endpoints ​

List Patients ​

http
GET /ext/latest/patients
Authorization: Bearer {token}

Query Parameters:

  • externalId (optional) — Filter by external ID
  • firstName (optional) — Filter by first name
  • lastName (optional) — Filter by last name
  • dob (optional) — Filter by date of birth (YYYY-MM-DD)
  • email (optional) — Filter by email
  • limit (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:

  1. Exact externalId match (when provided)
  2. Fuzzy demographic match (requires dob + gender exact match, scores on name/address/telecom)
  3. 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 ​

FieldTypeCreateUpdateDescription
patientIdstring——System-generated UUID (read-only)
clientIdstring——Owning client ID (read-only)
firstNamestringrequiredoptionalFirst name
lastNamestringrequiredoptionalLast name
middleNamestringoptionaloptionalMiddle name (nullable)
dobstringrequiredoptionalDate of birth (YYYY-MM-DD)
genderstringrequiredoptionalSex (e.g., Male, Female)
emailstringoptionaloptionalEmail address (nullable)
phonestringoptionaloptionalPrimary phone (nullable)
faxNumberstringoptionaloptionalFax number (nullable)
salutationstringoptionaloptionalSalutation (nullable)
mrnstringoptionaloptionalMedical record number (nullable)
externalIdstringoptionaloptionalExternal system ID (nullable)
patientStatusstring——Active or Inactive (read-only)
altAddressesarrayoptionaloptionalArray of addresses (see below)
altTelecomsarrayoptionaloptionalArray of telecom methods (see below)
altNamesarrayoptionaloptionalArray of alternate names (see below)

Address Object ​

FieldTypeRequiredDescription
address1stringyesStreet address
address2stringnoSuite/unit
citystringyesCity
statestringnoState
zipstringnoZIP code
currentbooleannoWhether this is the current address

Telecom Object ​

FieldTypeRequiredDescription
typestringyesMC=Mobile, HP=Home, WP=Work
valuestringyesPhone number or contact value

AltName Object ​

FieldTypeRequiredDescription
typestringyesmaiden, firstname, lastname, or middlename
valuestringyesThe 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 ​

StatusCodeDescription
400VALIDATION_ERRORMissing or invalid fields
401FORBIDDENMissing authentication or invalid token
403FORBIDDENInsufficient scopes
404RESOURCE_NOT_FOUNDPatient not found
409RESOURCE_EXISTSDuplicate MRN or email
422INVALID_REFERENCEReferenced client does not exist

Vivlio Health API Documentation