Skip to content

Contributions ​

Upload a document for a patient so Vivlio Health can contribute it back to the health information network on your behalf. When another network participant queries for this patient's records, contributed documents are among the results Vivlio Health can return — for example, a discharge summary, a scanned form, or any record you hold for a patient that isn't otherwise flowing through your standard clinical data feed.

Authentication ​

Requires a Client token with scopes:

  • contribution:read — For GET endpoints
  • contribution:write — For the create endpoint

Overview ​

Uploading a contribution is a three-step flow:

  1. Create the contribution — POST /patients/{patientId}/contributions with the file's metadata. This returns a short-lived, pre-signed upload URL.
  2. Upload the file — PUT the file's bytes directly to the returned uploadUrl. This request goes straight to storage, not through the Vivlio Health API.
  3. Check the status — GET /patients/{patientId}/contributions/{contributionId} to confirm the upload was received and processed.
http
POST /ext/latest/patients/{patientId}/contributions
Authorization: Bearer {token}
http
PUT {uploadUrl from step 1}
Content-Type: {the mimeType you declared in step 1}
http
GET /ext/latest/patients/{patientId}/contributions/{contributionId}
Authorization: Bearer {token}

Not Yet Retrievable Elsewhere

Contributed files are not currently retrievable through Patient Files or any other read endpoint on this API. Use the contribution status endpoint below to confirm an upload succeeded. This will change in a future release once additional processing is wired into this flow — see the Changelog for updates.

Endpoints ​

Create a Contribution ​

http
POST /ext/latest/patients/{patientId}/contributions
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

FieldTypeRequiredDescription
fileNamestringyesOriginal file name (1–255 characters)
mimeTypestringyesMIME type — must be one of the supported types
fileSizeintegernoFile size in bytes. Reconciled against the actual uploaded size once received — see Uploading the File
documentTitlestringnoHuman-readable title for the document (max 255 characters)
dateOfServicestringnoDate of service the document relates to (ISO 8601, e.g. 2026-06-01)
appointmentIdstringone of appointmentId / extAppointmentId requiredThe workflow/appointment ID from this API (the appointmentId returned by the Appointments endpoints) — see Linking to a Retrieval Request
extAppointmentIdstringone of appointmentId / extAppointmentId requiredYour external system's appointment ID (the externalId/extApptId used when creating appointments) — see Linking to a Retrieval Request
json
{
  "fileName": "discharge-summary.pdf",
  "mimeType": "application/pdf",
  "fileSize": 245000,
  "documentTitle": "Discharge Summary",
  "dateOfService": "2026-08-01",
  "appointmentId": "b1a2c3d4-5678-90ab-cdef-1234567890ab"
}

Note: Use either appointmentId or extAppointmentId — exactly one is required. See Linking to a Retrieval Request.

Response (200 OK):

json
{
  "data": {
    "contributionId": "019fd79e-253a-70d9-9a3d-43223740f1c1",
    "uploadUrl": "https://vivlio-health-file-uploads-prod.s3.amazonaws.com/...?X-Amz-Signature=...",
    "expiresAt": "2026-08-06T15:38:00.000Z",
    "status": "Upload In Progress..."
  }
}
FieldTypeDescription
contributionIdstringSystem-generated contribution ID — use this for all follow-up calls
uploadUrlstringPre-signed URL to PUT the file to. Expires in 15 minutes.
expiresAtstringISO 8601 timestamp of when uploadUrl expires
statusstringInitial status — always Upload In Progress... at creation

Content-Type Must Match

The PUT request to uploadUrl must include a Content-Type header that exactly matches the mimeType you declared when creating the contribution, or the upload will be rejected with a signature error.

List Contributions ​

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

Query Parameters:

  • limit (optional) — Page size (default: 10, max: 100)
  • offset (optional) — Page offset (default: 0)

Response:

json
{
  "data": [
    {
      "contributionId": "019fd79e-253a-70d9-9a3d-43223740f1c1",
      "fileName": "discharge-summary.pdf",
      "fileSize": 245000,
      "mimeType": "application/pdf",
      "status": "Upload Completed",
      "scanStatus": "NOT APPLICABLE",
      "hieQueryId": null,
      "documentTitle": "Discharge Summary",
      "dateOfService": "2026-08-01",
      "createdAt": "2026-08-06T15:23:00.000Z"
    }
  ],
  "limit": 10,
  "offset": 0,
  "total": 1,
  "hasMore": false
}

Results are ordered newest first. See Pagination for general pagination behavior.

Get Contribution Status ​

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

Response:

json
{
  "data": {
    "contributionId": "019fd79e-253a-70d9-9a3d-43223740f1c1",
    "fileName": "discharge-summary.pdf",
    "fileSize": 245000,
    "mimeType": "application/pdf",
    "status": "Upload Completed",
    "scanStatus": "NOT APPLICABLE",
    "hieQueryId": null,
    "documentTitle": "Discharge Summary",
    "dateOfService": "2026-08-01",
    "createdAt": "2026-08-06T15:23:00.000Z"
  }
}

Returns 404 RESOURCE_NOT_FOUND if the contribution doesn't exist, or belongs to a different patient or client.

Contribution Object Fields ​

FieldTypeDescription
contributionIdstringSystem-generated contribution ID
fileNamestringFile name, as provided at creation (sanitized)
fileSizenumberFile size in bytes. Reflects the actual uploaded size once the upload completes, not the originally-declared estimate
mimeTypestringMIME type, as provided at creation
statusstringUpload status — see Status Values
scanStatusstringReserved for future malware-scanning support. Currently always NOT APPLICABLE
hieQueryIdstringThe retrieval request this contribution also counts toward, if any (see Linking to a Retrieval Request)
documentTitlestringHuman-readable title, if provided
dateOfServicestringDate of service, if provided (YYYY-MM-DD)
createdAtstringCreation timestamp (ISO 8601)

Status Values ​

StatusMeaning
Upload In Progress...Contribution created; waiting for the file to be PUT to uploadUrl
Upload CompletedThe file was received and confirmed non-empty
Upload EmptyThe file was received but was zero bytes — treat as a failed upload and retry
Upload FailedNo file was received within 45 minutes of creation — the uploadUrl has long since expired; create a new contribution to retry

Checking Status After Upload

There's a short delay between finishing your PUT to uploadUrl and the status reflecting Upload Completed — it's processed asynchronously, typically within seconds. If you poll immediately after the PUT completes and still see Upload In Progress..., wait a moment and check again.

Uploading the File ​

Step 2 of the flow — after creating the contribution, upload the actual file directly to storage:

http
PUT {uploadUrl}
Content-Type: {mimeType declared at creation}

{binary file contents}
  • The Vivlio Health API never receives the file bytes directly — this avoids request size limits and keeps large files off the API path entirely.
  • uploadUrl expires 15 minutes after the contribution is created. If it expires before you upload, the PUT will fail — create a new contribution rather than retrying the same contributionId.
  • The Content-Type header on your PUT must exactly match the mimeType you declared when creating the contribution, or the request is rejected.
  • The declared fileSize is only an initial estimate. Once the upload is received, the stored fileSize is corrected to match the actual number of bytes uploaded.

Upload Errors Come From Storage, Not the API

If your PUT to uploadUrl fails (expired URL, mismatched Content-Type, network error), the error response comes directly from the storage service, not from a Vivlio Health API error response — it won't have the structured error format used elsewhere in this API.

Linking to a Retrieval Request ​

Every contribution must be linked to an outstanding record-retrieval request your organization previously made. Provide exactly one of:

  • appointmentId — the workflow/appointment ID from this API (the appointmentId value returned by the Appointments endpoints)
  • extAppointmentId — your external system's appointment identifier (the externalId/extApptId you supplied when creating the appointment)

Providing both, or neither, returns 400 VALIDATION_ERROR.

json
{ "appointmentId": "b1a2c3d4-5678-90ab-cdef-1234567890ab" }
json
{ "extAppointmentId": "EHR-APPT-98765" }
  • The linked appointment must belong to the same patient and client, must have an active workflow, and must have an outstanding (not yet fulfilled) retrieval request — otherwise the request returns 404 RESOURCE_NOT_FOUND.
  • It's only marked fulfilled once the file upload actually completes, not at creation time.
  • If two contributions are submitted for the same retrieval request, the first one to finish uploading wins; the other still uploads successfully but does not become the fulfillment record.

Supported File Types ​

MIME TypeTypical Use
application/pdfScanned documents, forms
image/jpegPhotos, scanned images
image/pngScreenshots, scanned images
image/tiffHigh-resolution scans
text/plainPlain text documents
text/xmlStructured clinical documents (e.g. CCDA)
application/xmlStructured clinical documents (e.g. CCDA)

Files up to 100 MB are supported. Any other MIME type is rejected with 400 VALIDATION_ERROR at creation time, before an upload URL is issued.

Code Examples ​

Node.js ​

javascript
async function createContribution(token, patientId, { fileName, mimeType, fileSize, documentTitle, dateOfService, appointmentId }) {
  const response = await fetch(
    `https://api.vivliohealth.io/ext/latest/patients/${patientId}/contributions`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ fileName, mimeType, fileSize, documentTitle, dateOfService, appointmentId }),
    }
  );
  return response.json();
}

async function uploadContributionFile(uploadUrl, mimeType, fileBuffer) {
  const response = await fetch(uploadUrl, {
    method: 'PUT',
    headers: { 'Content-Type': mimeType },
    body: fileBuffer,
  });
  if (!response.ok) {
    throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
  }
}

async function getContributionStatus(token, patientId, contributionId) {
  const response = await fetch(
    `https://api.vivliohealth.io/ext/latest/patients/${patientId}/contributions/${contributionId}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return response.json();
}

// Full round trip
async function contributeFile(token, patientId, fileBuffer, fileName, mimeType) {
  const { data } = await createContribution(token, patientId, { fileName, mimeType, fileSize: fileBuffer.length });
  await uploadContributionFile(data.uploadUrl, mimeType, fileBuffer);

  // Poll until the upload is confirmed
  let status = data.status;
  while (status === 'Upload In Progress...') {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    const result = await getContributionStatus(token, patientId, data.contributionId);
    status = result.data.status;
  }
  return status;
}

Python ​

python
import requests
import time

def create_contribution(token, patient_id, file_name, mime_type, file_size=None, **extra):
    response = requests.post(
        f'https://api.vivliohealth.io/ext/latest/patients/{patient_id}/contributions',
        headers={'Authorization': f'Bearer {token}'},
        json={'fileName': file_name, 'mimeType': mime_type, 'fileSize': file_size, **extra}
    )
    response.raise_for_status()
    return response.json()

def upload_contribution_file(upload_url, mime_type, file_bytes):
    response = requests.put(
        upload_url,
        headers={'Content-Type': mime_type},
        data=file_bytes
    )
    response.raise_for_status()

def get_contribution_status(token, patient_id, contribution_id):
    response = requests.get(
        f'https://api.vivliohealth.io/ext/latest/patients/{patient_id}/contributions/{contribution_id}',
        headers={'Authorization': f'Bearer {token}'}
    )
    response.raise_for_status()
    return response.json()

def contribute_file(token, patient_id, file_bytes, file_name, mime_type):
    result = create_contribution(token, patient_id, file_name, mime_type, file_size=len(file_bytes))
    data = result['data']

    upload_contribution_file(data['uploadUrl'], mime_type, file_bytes)

    status = data['status']
    while status == 'Upload In Progress...':
        time.sleep(2)
        status_result = get_contribution_status(token, patient_id, data['contributionId'])
        status = status_result['data']['status']

    return status

Error Responses ​

StatusCodeDescription
400VALIDATION_ERRORInvalid request body — unsupported mimeType, fileSize too large, missing required fields, both appointmentId and extAppointmentId provided, or neither provided (exactly one is required)
401UNAUTHORIZEDMissing authentication or invalid token
403FORBIDDENInsufficient scopes (need contribution:read or contribution:write)
404RESOURCE_NOT_FOUNDPatient or contribution not found, or the appointment identified by appointmentId/extAppointmentId doesn't exist, doesn't belong to this patient/client, or has no outstanding retrieval request
500INTERNAL_ERRORError creating or retrieving the contribution

Compliance and Security ​

HIPAA/Security

All contribution activity is subject to your organization's privacy and security policies. Creation, listing, and status checks are logged for audit compliance.

  • Uploads are validated against a strict file-type allowlist and a 100 MB size limit before an upload URL is ever issued.
  • Upload URLs are single-use, time-limited (15 minutes), and scoped to a single file — they cannot be reused to overwrite a different file.
  • Contributions are always scoped to the patient and client identified by your access token; a contribution cannot be created, listed, or read across clients or patients.
  • Only upload documents you have the right to share with the broader health information network on this patient's behalf.

Vivlio Health API Documentation