Form Definition V2 API's

This is a group of new API's for querying Form Definitions (Non form data). Their usage should be prioritised over the usage of v1 APIs

Query form definitions (11.5.0)

Route: POST or QUERY /api/v2.0/forms (Requires authentication)

Description: Returns form definitions matching the supplied filters, sorted by key ascending then version descending, optionally paged with a cursor.

NOTE

Both the standard POST verb and the non-standard QUERY verb are accepted on this route and invoke the same action, producing an identical response for the same body. Most clients should use POST; QUERY is provided for clients/tooling that distinguish safe, cacheable "read" bodies from POST.

Request

Property	Type	Required	Description
layout	"Wizard" | "Document"	No	Restrict results to forms of this layout type.
formKeys	array of { key, versions[] }	No	Restrict results to the given form keys. If versions is empty for a key, all versions of that key are considered; otherwise only the listed versions.
metadata	array of { key, value }	No	Restrict results to forms whose metadata contains all of the given key/value pairs (combined with AND, matched case-insensitively).
latest	"Version" | "CreatableVersion"	No	Collapse results to one version per form key. Version picks the highest version regardless of delivery status. CreatableVersion picks the highest version at or above the tenant environments minimum delivery status (a form key with no qualifying version is dropped from the results). Omit to return every matching version.
searchTerm	string	No	Case-insensitive substring match against the form key or its title. Max length 200.
pageSize	integer	No	Number of items to return. Must be between 1 and 200 if supplied. Omit to return the entire matching, sorted result set as a single page.
cursor	string	No	Opaque cursor from a previous response's pageInfo.startCursor/endCursor, used to fetch the next/previous page. Only valid when pageSize is also supplied. Max length 512.
direction	"Forward" | "Backward"	No	Paging direction relative to cursor. Defaults to Forward.

{
    "layout": "Document",
    "searchTerm": "care",
    "pageSize": 10,
    "direction": "Forward"
}

Response

{
    "items": [
        {
            "key": "eolc",
            "version": 2,
            "layout": "Document",
            "title": "End of Life Care Plan",
            "classification": "Plans",
            "metadata": {
                "owner": "palliative-care-team"
            }
        }
    ],
    "pageInfo": {
        "startCursor": "MXxhMWIyYzNkNHxlb2xjfDI",
        "endCursor": "MXxhMWIyYzNkNHxlb2xjfDI",
        "hasNextPage": true,
        "hasPreviousPage": false
    }
}

startCursor/endCursor are opaque, URL-safe Base64 strings — treat them as tokens to echo back, not as data to decode or construct.

To fetch the next page, send another request with the same filters plus pageSize and cursor set to the previous response's pageInfo.endCursor:

{
    "layout": "Document",
    "searchTerm": "care",
    "pageSize": 10,
    "cursor": "MXxhMWIyYzNkNHxlb2xjfDI",
    "direction": "Forward"
}

To page backward from a known cursor, set direction to "Backward" and use pageInfo.startCursor instead.

Validation rules

All request validation failures return 400 with a standard ASP.NET ValidationProblemDetails body, with errors keyed by property name (e.g. PageSize, FormKeys[0].Key, Cursor):

• searchTerm — maximum length 200.
• pageSize — when supplied, must be between 1 and 200 inclusive.
• cursor — can only be supplied alongside pageSize; maximum length 512; must decode successfully and its embedded filter fingerprint must match the rest of the request body, otherwise the request fails with "The cursor does not match the supplied filters." (a cursor obtained under one set of filters cannot be reused with different filters or search terms).
• formKeys — no more than 100 entries; no duplicate keys (case-insensitive); each key must match the standard resource key pattern (letters, digits, _ and - only); each entry in versions must be greater than 0.
• metadata — no more than 20 entries; each entry's key and value must both be non-empty.
• layout, latest, direction — must be a valid value of their respective enum, when supplied.

Example: invalid request

{
    "pageSize": 0
}

{
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "PageSize": ["'Page Size' must be between 1 and 200."]
    }
}

Error handling and standard HTTP response codes

Code	Description
200	Success - The query executed and the (possibly empty) matching page of results is returned.
400	Bad Request - The request body failed validation (see above) or was otherwise malformed.
401	Unauthorized - The request did not include a valid authenticated user.