Provider Management
Manage providers within your client organization.
Authentication
Requires a Client token with scopes:
provider:read— For GET endpointsprovider:write— For POST/PUT/DELETE endpoints
Endpoints
List Providers
http
GET /ext/latest/providers
Authorization: Bearer {token}Query Parameters:
listMode(optional) — Filter mode:active(default) oralllimit(optional) — Page size (default: 10, max: 100)offset(optional) — Page offset (default: 0)
Response:
json
{
"data": [
{
"providerId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"providerName": "Dr. John Smith",
"npi": "1234567890",
"externalId": "EHR-PROV-12345",
"integrationSource": "Athena",
"active": true
}
],
"limit": 10,
"offset": 0,
"hasMore": false
}Get Provider
http
GET /ext/latest/providers/{providerId}
Authorization: Bearer {token}Response:
json
{
"data": { ... }
}Create Provider
http
POST /ext/latest/providers
Content-Type: application/json
Authorization: Bearer {token}Request Body:
json
{
"providerName": "Dr. John Smith",
"npi": "1234567890",
"externalId": "EHR-PROV-12345",
"integrationSource": "Athena"
}Response (201 Created):
json
{
"data": { ... }
}Update Provider
http
PUT /ext/latest/providers/{providerId}
Content-Type: application/json
Authorization: Bearer {token}Request Body: (all fields optional)
json
{
"providerName": "Dr. John Q. Smith",
"npi": "1234567890"
}Response:
json
{
"data": { ... }
}Delete Provider
http
DELETE /ext/latest/providers/{providerId}
Authorization: Bearer {token}Response (204 No Content): (no body)
Provider Object Fields
| Field | Type | Create | Update | Description |
|---|---|---|---|---|
providerId | string | — | — | System-generated UUID (read-only) |
clientId | string | — | — | Owning client ID (read-only) |
providerName | string | required | optional | Full provider name |
npi | string | optional | optional | National Provider Identifier (10 digits) |
externalId | string | optional | optional | External system identifier (max 64 chars, nullable) |
integrationSource | string | optional | optional | Integration source (e.g., Athena, Epic, nullable). Unrecognized values are silently set to null. |
active | boolean | — | — | Active status (read-only; use DELETE to deactivate) |
Examples
Node.js
javascript
async function createProvider(token, providerData) {
const response = await fetch('https://api.vivliohealth.io/ext/latest/providers', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`
},
body: JSON.stringify(providerData)
});
if (!response.ok) {
const error = await response.json();
throw new Error(`Failed to create provider: ${error.error.message}`);
}
return response.json();
}
async function listActiveProviders(token) {
const response = await fetch(
'https://api.vivliohealth.io/ext/latest/providers?listMode=active',
{ headers: { Authorization: `Bearer ${token}` } }
);
return response.json();
}Python
python
import requests
def create_provider(token, provider_data):
response = requests.post(
'https://api.vivliohealth.io/ext/latest/providers',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {token}'
},
json=provider_data
)
response.raise_for_status()
return response.json()
def list_providers(token, list_mode='active'):
response = requests.get(
'https://api.vivliohealth.io/ext/latest/providers',
headers={'Authorization': f'Bearer {token}'},
params={'listMode': list_mode}
)
response.raise_for_status()
return response.json()Integration Sources
Common integration sources include:
Athena— AthenaHealthEpic— Epic SystemsCerner— Cerner/Oracle- Other EHR systems as integrated
Custom Integration Sources
If your integration source isn't listed, contact Vivlio Health support to add it to the system.
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 | Provider not found |
| 409 | RESOURCE_EXISTS | Duplicate NPI |
| 422 | INVALID_REFERENCE | Referenced client does not exist |
Common Use Cases
List Active Providers
bash
curl "https://api.vivliohealth.io/ext/latest/providers?listMode=active&limit=25" \
-H "Authorization: Bearer {token}"Create Provider with NPI
bash
curl -X POST https://api.vivliohealth.io/ext/latest/providers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
"providerName": "Dr. Sarah Jones",
"npi": "9876543210",
"integrationSource": "Epic"
}'Search All Providers (Including Inactive)
bash
curl "https://api.vivliohealth.io/ext/latest/providers?listMode=all" \
-H "Authorization: Bearer {token}"