FindCases_v1 - Medaxion/open_api_resources GitHub Wiki

Find Cases Endpoint

The Find Cases function of the paginated_case_queries endpoint retrieves one to many cases across multiple patients based on general case attributes. This endpoint performs a paginated search using broad, non-patient-specific filters such as status, location, date ranges, and operational metadata.

This endpoint is optimized for retrieving the state of many cases in bulk, based on flexible and extensible filtering.

In contrast, the Find Case endpoint is designed for use cases where the query is focused on one specific patient, using identifying information like name, DOB, or case number.

HTTP Request

  • Method: POST
  • Content-Type: application/json or application/xml

URL Format

POST => X:{authorization_token}@{base_url}/open_api/v1/paginated_case_queries.(xml|json)

Request Parameters

Required and Optional Query Parameters

Required:

  • date_range.begin
  • limit

Optional parameters:

  • date_range.end
  • date_target (defaults to scheduled_at)
  • practice_ids
  • location_ids
  • status (one or more allowed values)
    • Available values:
      • UNCONFIRMED - Case created, no scheduled DoS
      • PREARRIVE - Case scheduled, not in the hands of a Clinician
      • PREOP - Patient has arrived, but Anesthesia Start not set
      • INTRAOP - Anesthesia Start set, Anesthesia Stop not set
      • POSTOP - Anesthesia Stop set
      • ABANDONED - Case Preop or Intraop, abandons at 11:30pm local to the case, for inactivity
      • CANCELLED - Case was cancelled, manually or by system/feed
  • ops_data (requires case_identifier="true" on each datum)
  • offset (defaults to 0)

If both practice_ids and location_ids are included, cases matching either will be returned (additive logic).

Unconfirmed cases are excluded by default unless explicitly included in the status array.

Sample Request

JSON Example (cURL)

curl -X POST \
  https://X:your_token@your_site.medaxion.com/open_api/v1/case_queries.json \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "patient_first_name": "Timothy",
      "patient_last_name": "Lombart",
      "patient_dob": "20120102",
      "case_number": "ABC456",
      "patient_number": "M12",
      "status": "POSTOP",
      "location_id": "42",
      "postop_at": {
        "begin": "201902241930",
        "end": "202003241930"
      },
      "ops_data": [
        {
          "hidden": "true",
          "case_identifier": "true",
          "key": "lorem",
          "value": "ipsum"
        }
      ]
    }
  }

JSON Request Structure

{
  "paginated_case_query": {
    "status": [
      "POSTOP",
      "INTRAOP",
      "UNCONFIRMED"
    ],
    "practice_ids": [4],
    "location_ids": [324, 325, 328],
    "date_target": "scheduled_at",
    "date_range": {
      "begin": "20240418215325",
      "end": "20250418215325"
    },
    "ops_data": [
      {
        "case_identifier": "true",
        "key": "lorem",
        "value": "ipsum"
      },
      {
        "case_identifier": "true",
        "key": "foo",
        "value": "bar"
      }
    ],
    "limit": 100,
    "offset": 0
  }
}

XML Request Structure

<paginated-case-query>
  <status type="array">
    <status>POSTOP</status>
    <status>INTRAOP</status>
    <status>UNCONFIRMED</status>
  </status>
  <practice-ids type="array">
    <practice-id type="integer">4</practice-id>
  </practice-ids>
  <location-ids type="array">
    <location-id type="integer">324</location-id>
    <location-id type="integer">325</location-id>
    <location-id type="integer">328</location-id>
  </location-ids>
  <date-target>scheduled_at</date-target>
  <date-range>
    <begin type="dateTime">2024-04-18T17:53:25-04:00</begin>
    <end type="dateTime">2025-04-18T17:53:25-04:00</end>
  </date-range>
  <ops-data type="array">
    <ops-data-datum case_identifier="true">
      <key>lorem</key>
      <value>ipsum</value>
    </ops-data-datum>
    <ops-data-datum case_identifier="true">
      <key>foo</key>
      <value>bar</value>
    </ops-data-datum>
  </ops-data>
  <limit type="integer">100</limit>
  <offset type="integer">0</offset>
</paginated-case-query>

HTTP Status Codes

Status Code Description
201 Cases retrieved successfully.
422 Invalid or malformed query parameters.
500 Unexpected server error.

Response Format

JSON Response

{
  "cases": [
    {
      "case_id": 306125,
      "scheduled_at": "2024-08-30T13:00:00Z",
      "status": "UNCONFIRMED",
      "synthetic_case_id": "database-unnamed-306125",
      "updated_at": "2024-08-30T20:46:46Z",
      "practice": {
        "practice_id": 1,
        "name": "TEST"
      },
      "location": {
        "location_id": 324,
        "name": "Alpha",
        "location_tag": {
          "name": "Main",
          "number": "1902",
          "sysid": "1902",
          "syslabel": "1902"
        }
      },
      "patient": {
        "patient_id": 311852,
        "first_name": "Test",
        "last_name": "Smith",
        "date_of_birth": null
      },
      "ops_data": [
        {
          "key": "foo",
          "value": "bar",
          "hidden": false
        }
      ]
    }
  ]
}

XML Response

<?xml version="1.0" encoding="utf-8"?>
<cases type="array">
  <case>
    <case-id type="integer">306125</case-id>
    <scheduled-at type="dateTime">2024-08-30T13:00:00Z</scheduled-at>
    <status>UNCONFIRMED</status>
    <synthetic-case-id>database-unnamed-306125</synthetic-case-id>
    <updated-at type="dateTime">2024-08-30T20:46:46Z</updated-at>
    <practice>
      <practice-id type="integer">1</practice-id>
      <name>TEST</name>
    </practice>
    <location>
      <location-id type="integer">324</location-id>
      <name>Alpha</name>
      <location-tag>
        <name>Main</name>
        <number>1902</number>
        <sysid>1902</sysid>
        <syslabel>1902</syslabel>
      </location-tag>
    </location>
    <patient>
      <patient-id type="integer">311852</patient-id>
      <first-name>Test</first-name>
      <last-name>Smith</last-name>
      <date-of-birth nil="true" />
    </patient>
    <ops-data type="array">
      <ops-datum>
        <key>foo</key>
        <value>bar</value>
        <hidden type="boolean">false</hidden>
      </ops-datum>
    </ops-data>
  </case>
  ...
</cases>

Important Notes

  • limit is required and cannot exceed the configured maximum (currently 1000).
  • If no cases match, a 201 response will return an empty cases array.
  • offset defaults to 0 if not specified.
  • The default date_target is scheduled_at if not included.
  • All datetime values must be provided in UTC format.
  • Cases matching either practice_ids OR location_ids will be returned (logical OR).
  • To filter by ops_data, each item must have case_identifier="true".

Terms of Use
© 2022-2025 Medaxion, Inc.

⚠️ **GitHub.com Fallback** ⚠️