Skip to content

Query Strings

Minimum CorEMR Version: 6.4.0

Starting in CorEMR version 6.4.0, CWS supports query strings for filtering.

Query strings allow you to send extra parameters to an endpoint to customize the data you receive. A query string is added to the end of a GET URL after a question mark (?) and contains key-value pairs, like ?key=value. If you need to include more than one parameter, you can separate them with an ampersand (&).

For example, if you want to filter a list of patients by their last name and limit the results to 10, you might send a request like /ws/v3/patients?lname=Smith&limit=10. Query strings in CWS make it easy to filter, sort, or paginate data without changing the endpoint itself, providing flexibility in how you access information.

Limiting and Ordering

Limit

The limit parameter specifies the maximum number of results to be returned.

Limit Example

/ws/patients?limit=10

Order

The order parameter specifies the sorting column and order that the data is displayed in.
The column and order are given in a comma-separated format.

Order must be either asc or desc.

Order Example

  • Column: lname
  • Order: asc
/ws/patients?order=lname,asc

Datatype Filters

Many fields are filterable in 6.4. These fields are indicated by a check mark in the 6.4 Filter column in the Get Return Fields table.

  • Bool

    Boolean filters can be specified in query parameters as either 0 or 1.

    Boolean Filter Example

    Request all chronic problems:

    /ws/problems?chronic=1

  • Date / Datetime

    Date filters must be in ISO 8601 format (1994-11-05).
    Single date filtering is not supported. All date fields must be filtered using a comma-separated date range (start_date,end_date).

    Date Filter Example

    Request alerts that were created between 1970-01-01 and 2024-01-01: 

    /ws/alerts/?created_date=1970-01-01,2024-01-01

  • String

    String filters are entered "as is", without the need for quotation marks.

    String Filter Examples

    Request all Male patients: 

    /ws/patients/?sex=M

    Request all patients with agency County: 

    /ws/patients/?agency=County

  • Integer

    Integer filters are entered "as is".

    Integer Filter Examples

    Request problems with severity of 5: 

    /ws/problems/?severity=5

    Request tasks in task category 6: 

    /ws/tasks/?task_category_id=6

Filtering Multiple Values

CWS supports filtering multiple values by using comma-separated lists.

Example Multi-Value Filter

To filter multiple values in a single field, you can comma-separate the values, like this: 

/ws/problems/?created_user_id=1,3,5

This example would return all problems that were created by users with IDs 1, 3 and 5.

Pagination

CWS supports pagination, using the page and per_page query strings.

Pagination Example

  • page: 1
  • per_page: 1
/ws/alerts/?page=1&per_page=1
Example response
{
    "records": [
        {
            "id": 1,
            "external_id": "example_external_id",
            "category_name": "Bottom Bunk",
            "category_id": 1,
            "created_date": "2022-08-05 16:16:01.000",
            "created_user": "example_user",
            "created_user_id": 1,
            "expires_date": null,
            "removed_date": "2022-08-05 16:16:23.000",
            "removed_user": "example_user",
            "removed_user_id": 1
        }
    ],
    "pagination": {
        "current_page": "1",
        "per_page": "1",
        "total_pages": 102,
        "total_records": 102,
        "next_page_url": "/ws/alerts/?page=2&per_page=1",
        "prev_page_url": null
    }
}

Note

Some endpoints, such as forms and reports require pagination and use it by default.