Search SOAP Notes¶

Search and filter SOAP notes across one or more criteria — including date range, case ID, and signature status. Returns a paginated result set.

Endpoint¶

GET /apis/v1/soap-context/search

Query Parameters¶

Parameter	Type	Required	Description
`patient_id`	integer	No	Filter by patient ID
`organisation_id`	integer	No	Filter by organization ID
`clinic_id`	integer	No	Filter by clinic ID
`appointment_id`	integer	No	Filter by a specific appointment ID
`spry_case_id`	string	No	Filter by case ID (e.g. `SPRY_CASE_69cd0c97e7562d613ea89bc7`)
`start_date_time`	string	No	Lower bound on `service_date_time` (ISO-8601, e.g. `2026-01-01T00:00:00`)
`end_date_time`	string	No	Upper bound on `service_date_time` (ISO-8601, e.g. `2026-05-31T23:59:59`)
`status`	string	No	Filter by signature status: `INCOMPLETED`, `COSIGN`, `REVISION`, or `COMPLETED`
`completed`	boolean	No	`true` to return only completed notes; `false` for incomplete notes
`payment_mode`	string	No	Comma-separated payment modes (e.g. `INSURANCE_PAY,SELF_PAY`)
`category`	string	No	Comma-separated note categories
`tags`	string	No	Comma-separated tags to filter by
`page`	integer	No	Page number (default: `1`)
`size`	integer	No	Records per page (default: `10`)
`sort_direction`	string	No	Sort order by `service_date_time`: `ASC` or `DESC` (default: `DESC`)

Request Examples¶

Filter by case and date range¶

curl --location '{base_url}/apis/v1/soap-context/search?patient_id=1172416&spry_case_id=SPRY_CASE_69cd0c97e7562d613ea89bc7&start_date_time=2026-01-01T00:00:00&end_date_time=2026-05-31T23:59:59&page=1&size=20' \
  --header 'Authorization: Bearer JWT_TOKEN'

Filter by status (completed notes only)¶

curl --location '{base_url}/apis/v1/soap-context/search?patient_id=1172416&status=COMPLETED&page=1&size=10' \
  --header 'Authorization: Bearer JWT_TOKEN'

Filter notes pending co-sign¶

curl --location '{base_url}/apis/v1/soap-context/search?clinic_id=412&status=COSIGN&page=1&size=25' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "code": 2000,
  "data": {
    "page": 1,
    "total_pages": 2,
    "size": 10,
    "total_elements": 14,
    "content": [
      {
        "context_id": "abc123def456",
        "patient_id": 1172416,
        "organisation_id": 638,
        "clinic_id": 412,
        "spry_case_id": "SPRY_CASE_69cd0c97e7562d613ea89bc7",
        "case_title": "Stable Burst Fracture",
        "appointment_id": 990812,
        "type": "FOLLOWUP_SOAP",
        "category": "SOAP",
        "service_date_time": "2026-05-12T10:00:00",
        "status": "COMPLETED",
        "completed": true,
        "completed_at": "2026-05-12T11:34:22",
        "submit_for_billing": true,
        "summary_doc_url": "soap_summary/1172416/d3f8a2bc-11e4-4c9b-9f1a-abc123456789.pdf",
        "short_summary_url": "soap_short_summary/1172416/e7c1b3ad-22f5-5d0c-af2b-bcd234567890.pdf",
        "billing_status": "BILLED",
        "is_soap_note_editable": false,
        "rendering_physician": 50112,
        "supervising_physician": null,
        "payment_mode": "INSURANCE_PAY",
        "tags": [],
        "created_at": "2026-05-12T09:55:00",
        "updated_at": "2026-05-12T11:34:22"
      },
      {
        "context_id": "def456ghi789",
        "patient_id": 1172416,
        "organisation_id": 638,
        "clinic_id": 412,
        "spry_case_id": "SPRY_CASE_69cd0c97e7562d613ea89bc7",
        "case_title": "Stable Burst Fracture",
        "appointment_id": 990600,
        "type": "PROGRESS_NOTE",
        "category": "SOAP",
        "service_date_time": "2026-04-28T14:00:00",
        "status": "COMPLETED",
        "completed": true,
        "completed_at": "2026-04-28T15:10:05",
        "submit_for_billing": true,
        "summary_doc_url": "soap_summary/1172416/f9d2c4be-33g6-6e1d-bg3c-cde345678901.pdf",
        "short_summary_url": null,
        "billing_status": "BILLED",
        "is_soap_note_editable": false,
        "rendering_physician": 50112,
        "supervising_physician": null,
        "payment_mode": "INSURANCE_PAY",
        "tags": [],
        "created_at": "2026-04-28T13:50:00",
        "updated_at": "2026-04-28T15:10:05"
      }
    ]
  },
  "message": "Success"
}

Response Fields¶

Pagination envelope (data)

Field	Type	Description
`page`	integer	Current page number
`total_pages`	integer	Total number of pages
`size`	integer	Page size requested
`total_elements`	integer	Total number of matching SOAP notes
`content`	array	List of SOAP note objects (see below)

SOAP note object (content[])

Field	Type	Description
`context_id`	string	Unique SOAP note identifier
`patient_id`	integer	Patient ID
`organisation_id`	integer	Organization ID
`clinic_id`	integer	Clinic ID
`spry_case_id`	string	Associated case ID
`case_title`	string	Title of the associated case
`appointment_id`	integer	Associated appointment ID, or `null`
`type`	string	SOAP note type (see Note Types)
`category`	string	Note category
`service_date_time`	string	Date and time of the clinical service
`status`	string	Signature status — `INCOMPLETED`, `COSIGN`, `REVISION`, or `COMPLETED`
`completed`	boolean	`true` when the note is fully signed and completed
`completed_at`	string	Timestamp when the note was completed, or `null`
`submit_for_billing`	boolean	`true` if the note has been submitted for billing
`summary_doc_url`	string	S3 key for the completed SOAP summary PDF, or `null` if not yet generated
`short_summary_url`	string	S3 key for the short summary PDF, or `null` if not yet generated
`billing_status`	string	Billing state for the note
`is_soap_note_editable`	boolean	Whether the note can still be edited
`rendering_physician`	integer	ID of the rendering (treating) physician
`supervising_physician`	integer	ID of the supervising physician, or `null`
`payment_mode`	string	Payment mode: `INSURANCE_PAY`, `SELF_PAY`, `CASH`, `CARD`, or `null`
`tags`	array	Custom tags attached to the note
`created_at`	string	Note creation timestamp
`updated_at`	string	Timestamp of the last update

Error Response¶

Code: 200 OK

{
  "code": 4000,
  "data": null,
  "message": "Bad request"
}

Signature Status Values¶

Value	Description
`INCOMPLETED`	Note has been started but not yet signed
`COSIGN`	Note is awaiting co-signature from a supervising physician
`REVISION`	Note has been sent back for revision
`COMPLETED`	Note is fully signed and locked

Notes¶

start_date_time and end_date_time filter on service_date_time (the date of service), not the creation or update timestamp.
Passing status=INCOMPLETED returns all notes that are not COMPLETED — i.e. it matches INCOMPLETED, COSIGN, and REVISION.
summary_doc_url and short_summary_url are S3 object keys, not pre-signed URLs. Both fields are null until the PDF generation job runs after the note is completed.
To list all notes for a patient without filters, use List SOAP Notes.
To retrieve a single note by ID, use Get SOAP Note.