Save Document¶

Save a document record linked to a patient. The file must already be uploaded to storage — use Upload File first to get the document_url and bucket_name.

Endpoint¶

POST /apis/v1/patient-document

Request Body¶

Parameter	Type	Required	Description
`patient_id`	integer	Yes	ID of the patient this document belongs to
`name`	string	Yes	Display name for the document
`document_url`	string	Yes	URL of the uploaded file; returned by Upload File
`bucket_name`	string	Yes	Storage bucket name; returned by Upload File
`document_type`	string	No	Free-text document type label (e.g., `"Insurance Card"`, `"Referral Letter"`)
`document_category`	string	No	Category enum (see Document Category Values)
`thumbnail_url`	string	No	URL of a thumbnail image for the document
`spry_case_id`	string	No	Associate the document with a specific case (`SPRY_CASE_<id>`)
`eligible_visit_count`	integer	No	Number of visits this document covers (used for authorization documents)
`notes`	string	No	Free-text notes about the document
`document_expiration_date`	string (datetime)	No	Expiration date of the document (`YYYY-MM-DDTHH:mm:ss`)
`receipt_date`	string (datetime)	No	Date the document was received (`YYYY-MM-DDTHH:mm:ss`)
`signature_status`	string	No	Signature state (see Signature Status Values)
`signed_by`	string	No	Name of the person who signed the document
`signed_at`	string (datetime)	No	Timestamp when the document was signed

Request¶

curl --location '{base_url}/apis/v1/patient-document' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "patient_id": 1172416,
    "name": "PEHP Insurance Card",
    "document_url": "https://storage.googleapis.com/us-phy-uploads/patients/1172416/documents/insurance-card.pdf",
    "bucket_name": "us-phy-uploads",
    "document_type": "Insurance Card",
    "document_category": "INSURANCE_CARD",
    "spry_case_id": "SPRY_CASE_69cd0c97e7562d613ea89bc7",
    "notes": "Primary insurance card — PEHP plan 2025-2026",
    "receipt_date": "2026-04-01T09:00:00"
  }'

Response¶

Success Response¶

Code: 200 OK

{
  "code": 2000,
  "data": {
    "id": 458312,
    "name": "PEHP Insurance Card",
    "patient_id": 1172416,
    "uploaded_by": 8821,
    "document_url": "https://storage.googleapis.com/us-phy-uploads/patients/1172416/documents/insurance-card.pdf",
    "unsigned_document_url": "https://storage.googleapis.com/us-phy-uploads/patients/1172416/documents/insurance-card.pdf",
    "thumbnail_url": null,
    "bucket_name": "us-phy-uploads",
    "document_type": "Insurance Card",
    "document_category": "INSURANCE_CARD",
    "spry_case_id": "SPRY_CASE_69cd0c97e7562d613ea89bc7",
    "case_title": "Stable Burst Fracture",
    "eligible_visit_count": 0,
    "notes": "Primary insurance card — PEHP plan 2025-2026",
    "document_expiration_date": null,
    "receipt_date": "2026-04-01T09:00:00",
    "signature_status": null,
    "signed_by": null,
    "signed_at": null,
    "original_file_name": "insurance-card.pdf",
    "created_at": "2026-04-01T12:00:00",
    "updated_at": "2026-04-01T12:00:00"
  },
  "message": "Success"
}

Response Fields¶

Field	Type	Description
`id`	integer	Unique document record ID
`name`	string	Display name of the document
`patient_id`	integer	Patient ID
`uploaded_by`	integer	User ID of the uploader
`document_url`	string	URL of the stored file
`unsigned_document_url`	string	URL to the unsigned version of the document
`thumbnail_url`	string	URL of the thumbnail, or `null`
`bucket_name`	string	Storage bucket
`document_type`	string	Free-text document type label
`document_category`	string	Document category enum value
`spry_case_id`	string	Associated case ID, or `null`
`case_title`	string	Title of the associated case, or `null`
`eligible_visit_count`	integer	Visits covered by this document
`notes`	string	Free-text notes
`document_expiration_date`	string	Expiration date, or `null`
`receipt_date`	string	Date document was received, or `null`
`signature_status`	string	Signature state, or `null`
`signed_by`	string	Signer name, or `null`
`signed_at`	string	Signature timestamp, or `null`
`original_file_name`	string	Original name of the uploaded file
`created_at`	string	Record creation timestamp
`updated_at`	string	Last update timestamp

Error Response¶

Code: 400 Bad Request

{
  "code": 4000,
  "message": "Error description",
  "data": null
}

Document Category Values¶

Value	Description
`PERSONAL_DETAILS`	Personal identification documents
`MEDICAL_HISTORY`	Past medical records and history
`DIAGNOSTIC_TESTS`	Lab results, imaging, diagnostic reports
`PROVIDER_NOTES`	Clinical notes from providers
`INSURANCE`	General insurance documents
`INSURANCE_CARD`	Insurance card images
`INSURANCE_VERIFICATION`	Insurance eligibility verification documents
`FINANCIAL_INFORMATION`	Financial and billing documents
`PROTOCOL`	Treatment protocol documents
`SOAP_SUMMARY_DOCUMENT`	SOAP note summaries
`POC_DOCUMENT`	Plan of care documents
`OTHER`	Documents that don't fit other categories

Signature Status Values¶

Value	Description
`COMPLETED`	Document has been signed
`INCOMPLETED`	Signature is pending
`COSIGN`	Awaiting co-signature
`REVISION`	Document requires revision before signing

Notes¶

Files must be uploaded with Upload File before calling this endpoint. This endpoint only stores metadata and a reference URL — it does not accept raw file data.
spry_case_id links the document to a case; use the spry_case_id returned by Add Case.
eligible_visit_count is relevant for authorization documents where the document covers a fixed number of visits.