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 endpointscontribution:write— For the create endpoint
Overview
Uploading a contribution is a three-step flow:
- Create the contribution —
POST /patients/{patientId}/contributionswith the file's metadata. This returns a short-lived, pre-signed upload URL. - Upload the file —
PUTthe file's bytes directly to the returneduploadUrl. This request goes straight to storage, not through the Vivlio Health API. - Check the status —
GET /patients/{patientId}/contributions/{contributionId}to confirm the upload was received and processed.
POST /ext/latest/patients/{patientId}/contributions
Authorization: Bearer {token}PUT {uploadUrl from step 1}
Content-Type: {the mimeType you declared in step 1}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
POST /ext/latest/patients/{patientId}/contributions
Content-Type: application/json
Authorization: Bearer {token}Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
fileName | string | yes | Original file name (1–255 characters) |
mimeType | string | yes | MIME type — must be one of the supported types |
fileSize | integer | no | File size in bytes. Reconciled against the actual uploaded size once received — see Uploading the File |
documentTitle | string | no | Human-readable title for the document (max 255 characters) |
dateOfService | string | no | Date of service the document relates to (ISO 8601, e.g. 2026-06-01) |
appointmentId | string | one of appointmentId / extAppointmentId required | The workflow/appointment ID from this API (the appointmentId returned by the Appointments endpoints) — see Linking to a Retrieval Request |
extAppointmentId | string | one of appointmentId / extAppointmentId required | Your external system's appointment ID (the externalId/extApptId used when creating appointments) — see Linking to a Retrieval Request |
{
"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
appointmentIdorextAppointmentId— exactly one is required. See Linking to a Retrieval Request.
Response (200 OK):
{
"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..."
}
}| Field | Type | Description |
|---|---|---|
contributionId | string | System-generated contribution ID — use this for all follow-up calls |
uploadUrl | string | Pre-signed URL to PUT the file to. Expires in 15 minutes. |
expiresAt | string | ISO 8601 timestamp of when uploadUrl expires |
status | string | Initial 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
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:
{
"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
GET /ext/latest/patients/{patientId}/contributions/{contributionId}
Authorization: Bearer {token}Response:
{
"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
| Field | Type | Description |
|---|---|---|
contributionId | string | System-generated contribution ID |
fileName | string | File name, as provided at creation (sanitized) |
fileSize | number | File size in bytes. Reflects the actual uploaded size once the upload completes, not the originally-declared estimate |
mimeType | string | MIME type, as provided at creation |
status | string | Upload status — see Status Values |
scanStatus | string | Reserved for future malware-scanning support. Currently always NOT APPLICABLE |
hieQueryId | string | The retrieval request this contribution also counts toward, if any (see Linking to a Retrieval Request) |
documentTitle | string | Human-readable title, if provided |
dateOfService | string | Date of service, if provided (YYYY-MM-DD) |
createdAt | string | Creation timestamp (ISO 8601) |
Status Values
| Status | Meaning |
|---|---|
Upload In Progress... | Contribution created; waiting for the file to be PUT to uploadUrl |
Upload Completed | The file was received and confirmed non-empty |
Upload Empty | The file was received but was zero bytes — treat as a failed upload and retry |
Upload Failed | No 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:
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.
uploadUrlexpires 15 minutes after the contribution is created. If it expires before you upload, thePUTwill fail — create a new contribution rather than retrying the samecontributionId.- The
Content-Typeheader on yourPUTmust exactly match themimeTypeyou declared when creating the contribution, or the request is rejected. - The declared
fileSizeis only an initial estimate. Once the upload is received, the storedfileSizeis 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 (theappointmentIdvalue returned by the Appointments endpoints)extAppointmentId— your external system's appointment identifier (theexternalId/extApptIdyou supplied when creating the appointment)
Providing both, or neither, returns 400 VALIDATION_ERROR.
{ "appointmentId": "b1a2c3d4-5678-90ab-cdef-1234567890ab" }{ "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 Type | Typical Use |
|---|---|
application/pdf | Scanned documents, forms |
image/jpeg | Photos, scanned images |
image/png | Screenshots, scanned images |
image/tiff | High-resolution scans |
text/plain | Plain text documents |
text/xml | Structured clinical documents (e.g. CCDA) |
application/xml | Structured 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
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
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 statusError Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid request body — unsupported mimeType, fileSize too large, missing required fields, both appointmentId and extAppointmentId provided, or neither provided (exactly one is required) |
| 401 | UNAUTHORIZED | Missing authentication or invalid token |
| 403 | FORBIDDEN | Insufficient scopes (need contribution:read or contribution:write) |
| 404 | RESOURCE_NOT_FOUND | Patient 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 |
| 500 | INTERNAL_ERROR | Error 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.
