Documentation

Access Care Planning APIs follow standard RESTful conventions — using HTTP verbs (GET, POST, PUT, DELETE) to perform operations on resources, returning appropriate status codes, and structuring endpoints around nouns rather than actions.

The sections below cover the custom request parameters available for refining and filtering the data returned.

Endpoint Types - HTTP verbs

Endpoint types (HTTP verbs) define the intent of a request — whether you're fetching, creating, updating, or deleting a resource.

  • GET - For retrieving resources from the ACP database.

  • POST - For creating new resources

  • PATCH - For updating existing resources

  • PUT - Either to update an existing resource OR create a new resource (if one does not exist with the same identifier)

  • DELETE - To remove an existing resource

Standard GET request parameters

Most of our GET APIs have these standard request parameters for pagination and filtering.

  • start - Set the first result to retrieve. Integer.

  • limit - Set the number of records to retrieve. The maximum limit is 1000. Integer.

  • column - Set the column to sort by. String.

  • direction - Set the direction of the sort. Integer.

  • mql - Set any MQL query to filter the result set by.

  • include - A comma-separated list of fields to be returned by the API.

For example, if we had an entity called Animal with the fields

age, type, name

You could pass in the parameters:

start=0&limit=10&column=name&direction=0&mql=type=giraffe,age

This would return the first 10 results, starting at 0, sorted by name ascending that are giraffes over the age of 10.

MQL - Our Query Language

MQL (Mobizio Query Language) is a language and a framework designed for querying Access Care Planning entities via RESTful services. MQL string should be sent as a request parameter.

References

  • Selector: A selector in MQL is a word that represents an Entity property eg. A "Visit" entity will have a "startDateTime" property

  • Operator: An operator in MQL is one or more symbols that compare the value of a selector on its left with one or more values on its right, such that only true results are retrieved by the clause

  • Value: A value in MQL is a word or phrase that is used to validate against the entity being queried

Syntax

A simple query in MQL consists of a selector, followed by an operator, followed by one or more values.

[selector][operation][one or more values]

For example, if you want to get all the Visits that it's start date is less than or equal to a particular day, you should use the format below:

startDateTime<=2016-02-09T22:36:00.000Z 

OR

startDateTime=[2016-02-09T22:36:00.000Z]

You can write more criterias in a MQL string, separated by comma (,). This behaves as a logical AND operand (conjunction). For example:

&mql=plannedStartDateTime%3E%3D2016-07-15T00:00:00.000Z,deadline%3C%3D2016-07-15T14:25:33.118Z

You can also write one or more criterias using the OR operand (disjunction) by using two pipes (||)

&mql=plannedStartDateTime%3E%3D2016-07-15T00:00:00.000Z||deadline%3C%3D2016-07-15T14:25:33.118Z

Supported Operations

  • = (equality)

  • != (negation)

  • ~ (like)

  • > (greater than)

  • < (less than)

  • >= (greater than or equal)

  • <= (less than or equal)

  • * (wildcard)

  • [a,b,c] (in)

Reserved Characters

MQL has a list of reserved characters, please see below:

= ! ~ > < * , [ ] |

URL Encoding

If you wish to use any reserved characters in your queries, you have to URL encode the MQL string.

...&mql=[urlEncodedMqlString]...

Supported Datatypes

MQL supports both reference and primitive types.

  • boolean - expected values: true, false, 1, 0. For example: field=true or field=1

  • integer - Any value with type integer (32-bit signed integer -2,147,483,648 < 0 < 2,147,483,647). For example: field=1334

  • float - Any value with type float.

  • double - Any value with type double.

  • long - Any value with type long.

  • date - Formats yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd. For example: field=2026-01-01T12:34:56.000Z or field=2026-01-01

MQL Examples

  • String comparison: tenantTaskId~abcd

  • String comparison with wildcard: tenantTaskId~*bc*

  • Null checks: tenantTaskId=null, tenantTaskId!=null

  • Date: startDateTime<=2016-07-15T17:00:00.000Z

Example request:

https://[restEndpoint]/visits?column=plannedStartDateTime&direction=1&limit=500&mql=plannedStartDateTime%3E%3D2026-07-15T00:00:00.000Z,deadline%3C%3D2026-07-15T14:25:33.118Z&search=&start=0

MQL Matching Regex

([\w\.]+)(=|>=|<=|<|>|~|!=)(\[[^=><~!|*]+\]|[^,|]+)((?:\|\|(?:[\w\.]+)(?:=|>=|<=|<|>|~|!=)(?:\[[^=><~!|*]+\]|[^,|]+))*)

Explanation:

  • 1st matching group ([\w\.]+) Matches the variable name to be searched, and any full stops and other names of parent objects that may precede it

  • 2nd matching group (=|>=|<=|<|>|~|!=) Matches any of the operators supported by MQL.

  • 3rd matching group (\[[^=><~|]+\]|[^=><~|]+) Matches any characters that may be the value to be used as the right-hand operand, possibly contained within square brackets for the IN MQL operator.

  • Non-matching (?=,|$|\|\|) Checks that the preceding groups are followed by either the end of the MQL string ($), or the ',' or '||' characters (and excludes then from being included in the group if so)

  • 4th matching group ((?:\|\| <--Groups 1 - 4--> )*) Checks whether the Matched groups 1-3 are followed by an OR operator, and bundles everything following in that particular MQL expression into Matched group 4 if so

All this means that the following MQL expression:

  • test.description=This, is a test||test.name~Test*,test.id=[1,2,3]

would result in the first match returning the following matched groups:

  1. test.description

  2. =

  3. This, is a test

  4. ||test.name~Test*

with the next match returning the following matched groups:

  1. test.id

  2. =

  3. [1,2,3]

and so on...