Skip to content

Getting Started ​

Welcome to the Vivlio Health API documentation. This guide will help you get started with integrating our API into your healthcare application.

Prerequisites ​

Before you begin, you'll need:

  • API Credentials - Contact your Vivlio Health representative to receive:
    • API Key ID
    • Client ID
    • Client Secret
  • Technical Requirements:
    • HTTPS support
    • JSON parsing capabilities
    • OAuth 2.0 Client Credentials flow implementation

Environments ​

Vivlio Health provides two environments for API integration:

EnvironmentBase URLPurpose
QA/Sandboxhttps://test-api.vivliohealth.io/ext/latestQA testing with sample data
Productionhttps://api.vivliohealth.io/ext/latestLive production environment

TIP

VH will provide a secure link with client creds once you signup. Start with the Sandbox environment for initial integration work before going to Production.

Sandbox comes with test data

Your sandbox account is pre-loaded with synthetic patients that already have medical records attached. Once you have a token, call GET /patients to list them and use a returned patientId to immediately explore any Medical Records endpoint — no test data to create first. Note that synthetic records may be sparse or missing some fields present in production data; they are suitable for validating integration logic and response shape. See Sandbox Test Patients for details.

Authentication Flow ​

The Vivlio Health API uses OAuth 2.0 Client Credentials flow for authentication:

Step 1: Request an Access Token ​

bash
POST /oauth/requestToken
Content-Type: application/json

{
  "id": "your-api-key-id",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "grantType": "client_credentials"
}

Step 2: Receive Token Response ​

json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Token Expiration

Tokens expire after 60 minutes. Implement token refresh logic in your application to request a new token before expiration.

Step 3: Use Token in API Requests ​

Include the token in the Authorization header of all subsequent requests:

bash
GET /patients
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Quick Example ​

Here's a complete example of authenticating and fetching your pre-existing sandbox patients:

javascript
const BASE_URL = 'https://test-api.vivliohealth.io/ext/latest';

// 1. Request access token
const tokenResponse = await fetch(`${BASE_URL}/oauth/requestToken`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 'your-api-key-id',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    grantType: 'client_credentials',
    npi: 'your-10-digit-npi',
    purposeOfUse: ['TREAT']
  })
});

const { token } = await tokenResponse.json();

// 2. List pre-existing sandbox patients (no setup required)
const patientsResponse = await fetch(`${BASE_URL}/patients`, {
  headers: { 'Authorization': `Bearer ${token}` }
});

const { data: patients } = await patientsResponse.json();
console.log(patients);

// 3. Pull medical records for the first patient
const { patientId } = patients[0];
const recordsResponse = await fetch(`${BASE_URL}/patients/${patientId}/records/medications`, {
  headers: { 'Authorization': `Bearer ${token}` }
});

const records = await recordsResponse.json();
console.log(records);

Client Onboarding and File Pull Activation ​

Setting up your API credentials and building your integration can happen at any time — but retrieving patient records via file pull requires a separate activation step before it will work in production.

The full onboarding flow looks like this:

  1. Receive credentials — Vivlio Health provisions your Client ID, Client Secret, and API Key.
  2. Build and test — Develop your integration against the Sandbox environment using test patients.
  3. EPIC approval — Your organization must be approved by EPIC to query their network. Vivlio Health will guide you through this process.
  4. Vivlio Health enables transactions — Once EPIC approval is confirmed, Vivlio Health activates file pull capability for your client account in the system.
  5. Go live — After activation, your token can successfully trigger file pulls against production patient data.

File pulls are not available until activated

Even with valid credentials and correct scopes, calls that trigger a file pull will not return records until Vivlio Health has enabled transactions for your account. Contact your Vivlio Health representative to check your activation status or initiate the EPIC approval process.

Creating an appointment is the call that triggers a file pull. See Starting a Records Query.

Next Steps ​

Common Issues ​

Invalid Credentials ​

If you receive a 401 Unauthorized error when requesting a token, verify:

  • API Key ID is correct
  • Client ID and Client Secret match
  • Credentials are for the correct environment (dev/test/prod)

Token Expired ​

If you receive a 401 Unauthorized error on API calls:

  • Check if your token has expired (60-minute lifetime)
  • Request a new token using the OAuth flow

Insufficient Permissions ​

If you receive a 403 Forbidden error:

  • Verify your token includes the required scopes for the endpoint
  • See Authorization for scope requirements per endpoint

Vivlio Health API Documentation