Downloading Interaction Files

Clinical interactions in Hint can carry file attachments: lab report PDFs, uploaded documents, scanned forms, and files pushed by other partners. This guide shows how to turn those attachments into downloadable files.

The `files` array names the attachments

Every interaction response includes a files array. Each entry identifies one attachment:

{
  "id": "int-abc123",
  "type": "lab",
  "files": [
    { "id": "Fah-3TWDJuQ1MSe-lBTiPh", "filename": "lab-results.pdf" },
    { "id": "Znd8CviNr5RERx6L-v5auf", "filename": "scan.tiff" }
  ]
}

This tells you what is attached, but it is not itself downloadable. The underlying storage keys are private, so you request a short-lived signed URL for a file through one of two endpoints. The file id in the files array is the same id you pass to the single-file endpoint below.

Download every file on an interaction

List Interaction File Download URLs returns a signed URL for every file on the interaction, as a bare array:

GET /api/provider/interactions/{interaction_id}/files/download_urls

[
  {
    "id": "Fah-3TWDJuQ1MSe-lBTiPh",
    "filename": "lab-results.pdf",
    "url": "https://practice-bucket.s3.amazonaws.com/public/pat-123456/lab-results.pdf?X-Amz-Signature=EXAMPLE",
    "expires_at": "2026-07-01T12:05:00.000Z"
  },
  {
    "id": "Znd8CviNr5RERx6L-v5auf",
    "filename": "scan.tiff",
    "url": null,
    "expires_at": null
  }
]

This is the call to make when you are syncing an interaction and want every attachment in one round trip.

Download a single file

Get Interaction File Download URL returns one element of that same shape. Use it when you already hold a file id (from an earlier sync, a queued job, or a retry) and want a fresh URL for just that file without re-signing the rest:

GET /api/provider/interactions/{interaction_id}/files/{id}/download_url

{
  "id": "Fah-3TWDJuQ1MSe-lBTiPh",
  "filename": "lab-results.pdf",
  "url": "https://practice-bucket.s3.amazonaws.com/public/pat-123456/lab-results.pdf?X-Amz-Signature=EXAMPLE",
  "expires_at": "2026-07-01T12:05:00.000Z"
}

Downloads are PDF-only

Only files that resolve to application/pdf receive a signed url. The two endpoints handle a non-PDF differently:

On download_urls, a non-PDF stays in the array with url and expires_at set to null. It is not omitted, so you can tell "this attachment is not downloadable" apart from "this attachment does not exist".
On download_url, a non-PDF is a 422 Unprocessable Entity. When you ask for a specific file, a refusal is the honest answer.

An id that does not match any file on the interaction returns 404 Not Found on the single-file endpoint.

URLs are short-lived: sign at download time

The signed url expires roughly 5 minutes after it is issued (expires_at carries the exact time), and it is meant to be used once. Request it at the moment the user acts, then redirect them to (or fetch) the returned url right away.

Do not cache the URL, store it in your database, or precompute it during a scheduled sync. A URL signed during an overnight backfill will have expired long before anyone clicks it. Store the file id instead, and request a fresh URL for it whenever you need one - the same id returns a new URL every time you call.

sequenceDiagram
  participant App as Your app
  participant Hint as Hint Provider API
  App->>Hint: GET /interactions/{id}
  Hint-->>App: files [ { id, filename } ]
  App->>Hint: GET /interactions/{id}/files/{file_id}/download_url
  Hint-->>App: { url, expires_at }
  App->>App: Redirect user to url within 5 minutes

This is the mechanism behind the lab-report rule for patient-facing surfaces: to show a patient a lab's PDF report, take the report file's id from the interaction's files array and request its download_url.

Access and scope

These endpoints are practice-scoped like the rest of the Provider API, authorized with the practice's access token. A partner can download files on any interaction it can already read; the endpoints do not restrict downloads to files the calling partner uploaded. Files a Hint provider attached in the UI are in scope alongside files uploaded by partners.

Availability

Both endpoints are available from API version 2026-07-01 onward. Clients pinned to an earlier version receive a 404 on both routes. See Initial Data Sync for the broader pattern of reconciling interaction data when you first connect a practice.

The files array names the attachments