Skip to content

Provider Management ​

Manage providers within your client organization.

Authentication ​

Requires a Client token with scopes:

  • provider:read — For GET endpoints
  • provider: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) or all
  • limit (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 ​

FieldTypeCreateUpdateDescription
providerIdstring——System-generated UUID (read-only)
clientIdstring——Owning client ID (read-only)
providerNamestringrequiredoptionalFull provider name
npistringoptionaloptionalNational Provider Identifier (10 digits)
externalIdstringoptionaloptionalExternal system identifier (max 64 chars, nullable)
integrationSourcestringoptionaloptionalIntegration source (e.g., Athena, Epic, nullable). Unrecognized values are silently set to null.
activeboolean——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 — AthenaHealth
  • Epic — Epic Systems
  • Cerner — 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 ​

StatusCodeDescription
400VALIDATION_ERRORMissing or invalid fields
401FORBIDDENMissing authentication or invalid token
403FORBIDDENInsufficient scopes
404RESOURCE_NOT_FOUNDProvider not found
409RESOURCE_EXISTSDuplicate NPI
422INVALID_REFERENCEReferenced 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}"

Vivlio Health API Documentation