List Patient Documents¶

Lists the documents on a patient's chart — uploads, faxes, discharge letters — newest first.

Endpoint¶

GET /v2/patients/{patient_id}/documents

Path Parameters¶

Parameter	Type	Required	Description
`patient_id`	string	Yes	The patient whose documents to list. Another organisation's patient is reported as not found.

Query Parameters¶

Parameter	Type	Required	Description
`page`	integer	No	1-based page number. Defaults to `1`.
`page_size`	integer	No	Results per page. Defaults to `25`.

Request¶

curl --location '{base_url}/v2/patients/63120/documents' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "items": [
    {
      "id": "431757",
      "patient_id": "63120",
      "name": "discharge-letter.pdf",
      "document_type": "Discharge Report",
      "document_category": "OTHER",
      "spry_case_id": "SPRY-63120-2",
      "url": "https://example-bucket.s3.us-west-2.amazonaws.com/discharge-letter.pdf?X-Amz-Signature=...",
      "thumbnail_url": "https://example-bucket.s3.us-west-2.amazonaws.com/discharge-letter.png?X-Amz-Signature=...",
      "uploaded_by": "2094",
      "uploaded_by_name": "Morgan Delgado",
      "signature_status": null,
      "signed_at": null,
      "received_at": null,
      "shared_with_patient": false,
      "from_fax": false,
      "notes": null,
      "created_at": "2026-08-27T14:30:00Z",
      "updated_at": "2026-08-27T14:30:00Z"
    }
  ],
  "page": 1,
  "page_size": 25,
  "total": 1,
  "total_pages": 1
}

Response Fields¶

Field	Type	Description
`items`	array of object	The page of results. See Items.
`page`	integer	1-based page number.
`page_size`	integer	Results per page.
`total`	integer	Total results matching the query.
`total_pages`	integer	Total pages available.

Items¶

Field	Type	Description
`id`	string	The document id.
`patient_id`	string	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
`name`	string or null	The file name.
`document_type`	string or null	What the document is, as labelled when it was filed.
`document_category`	string or null	The chart section it is filed under.
`spry_case_id`	string or null	The case's business key.
`url`	string or null	The document, as a signed S3 link valid for about 15 minutes. Fetch it rather than storing it.
`thumbnail_url`	string or null	A preview image, signed like `url`.
`uploaded_by`	string or null	The user who filed the document.
`uploaded_by_name`	string or null
`signature_status`	string or null	Whether the document has been signed, when it needs a signature.
`signed_at`	string (date-time) or null
`received_at`	string (date-time) or null	When a faxed document arrived.
`shared_with_patient`	boolean or null	Whether the patient can see the document in the patient app.
`from_fax`	boolean or null	Whether the document arrived by fax.
`notes`	string or null
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

url and thumbnail_url are signed S3 links valid for about 15 minutes. Fetch them when you need them rather than storing them.
A patient outside your organisation is reported as 404, the same as one that doesn't exist.