Appearance
Form Instance APIs
These APIs are only applicable for AireForms deployments with associated persistence.
Get form instances by instance identifiers
Route: GET /api/patientforms?instanceGuid={instanceGuid} (Requires authentication) Permission: ListPatientForms
Description: Returns a list of all forms with the given instance identifiers
Example: /api/patientforms?instanceGuid=816eb663-cc1f-478d-8efe-5c068ec434f2&instanceGuid=ba63eed3-5901-4cb0-a48a-955eab32abcf
Response
json
[
{
"instanceGuid": "816eb663-cc1f-478d-8efe-5c068ec434f2",
"title": "End of Life Care Plan",
"createDateTimeUtc": "2020-01-09T16:41:34.813",
"lastModifiedDateTimeUtc": "2020-01-09T16:41:34.813",
"status": "Draft",
"isAmendable": true,
"key": "eolc",
"version": 1
},
{
"instanceGuid": "ba63eed3-5901-4cb0-a48a-955eab32abcf",
"title": "BMI Reporting",
"createDateTimeUtc": "2019-12-02T11:22:12.6",
"lastModifiedDateTimeUtc": "2019-12-02T11:22:32.297",
"status": "Complete",
"isAmendable": false,
"key": "bmi-reporting",
"version": 1
}
...
]Get form instances for a given patient
Route: GET /api/patientforms/{patientId} (Requires authentication) Permission: ListPatientForms
Description: Returns a list of all forms associated with the patientId
Example: /api/patientforms/488edeAB-5e8F-4e50-9137-24e377cf9436
Response
json
[
{
"instanceGuid": "816eb663-cc1f-478d-8efe-5c068ec434f2",
"title": "End of Life Care Plan",
"createDateTimeUtc": "2020-01-09T16:41:34.813",
"lastModifiedDateTimeUtc": "2020-01-09T16:41:34.813",
"status": "Draft",
"isAmendable": true,
"key": "eolc",
"version": 1
},
{
"instanceGuid": "ba63eed3-5901-4cb0-a48a-955eab32abcf",
"title": "BMI Reporting",
"createDateTimeUtc": "2019-12-02T11:22:12.6",
"lastModifiedDateTimeUtc": "2019-12-02T11:22:32.297",
"status": "Complete",
"isAmendable": false,
"key": "bmi-reporting",
"version": 1
}
...
]From 5.15.0 you can now use the following filters sent as query params:
pageSizealong withpageNumbercorrelationId
History of a particular form instance
Route: GET /api/patientforms/{patientId}/history/{instanceGuid} (Requires authentication) Permission: ListPatientForms
Description: Retrieves the history of an instance.
Example response
json
{
"compositeInstanceHistory": [
{
"instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
"instanceVersionGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
"createdByUserIdentifier": "4",
"createdDateTimeUtc": "2023-05-22T15:39:39.2878379",
"status": "New",
"isEditMilestone": true,
"isCompleted": false,
"isDeleted": false,
"deletedByUserIdentifier": null,
"deletedDateTimeUtc": null,
"key": "bmi-reporting",
"version": 1,
"viewLink": "/patient/117536d8-9ef2-49d2-Ae9e-f5afb330c78f/instance/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/version/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/view"
},
{
"instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
"instanceVersionGuid": "6ee55219-1e63-4f4f-83da-7e8077820c3d",
"createdByUserIdentifier": "4",
"createdDateTimeUtc": "2023-05-22T15:39:45.3373301",
"status": "Complete",
"isEditMilestone": false,
"isCompleted": true,
"isDeleted": false,
"deletedByUserIdentifier": null,
"deletedDateTimeUtc": null,
"key": "bmi-reporting",
"version": 1,
"viewLink": "/patient/117536d8-9ef2-49d2-Ae9e-f5afb330c78f/instance/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/version/6ee55219-1e63-4f4f-83da-7e8077820c3d/view"
},
{
"instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
"instanceVersionGuid": "62932da8-8d40-4e1a-9bc6-68240263107d",
"createdByUserIdentifier": "10",
"createdDateTimeUtc": "2023-05-22T15:39:52.867569",
"status": "Draft",
"isEditMilestone": true,
"isCompleted": false,
"isDeleted": false,
"deletedByUserIdentifier": null,
"deletedDateTimeUtc": null,
"key": "bmi-reporting",
"version": 1,
"viewLink": "/patient/117536d8-9ef2-49d2-Ae9e-f5afb330c78f/instance/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/version/62932da8-8d40-4e1a-9bc6-68240263107d/view"
},
{
"instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
"instanceVersionGuid": "ec5f403e-5752-44bb-9ca4-d76375d3ef6a",
"createdByUserIdentifier": "10",
"createdDateTimeUtc": "2023-05-22T15:40:02.33459",
"status": "Complete",
"isEditMilestone": false,
"isCompleted": true,
"isDeleted": false,
"deletedByUserIdentifier": null,
"deletedDateTimeUtc": null,
"key": "bmi-reporting",
"version": 1,
"viewLink": "/patient/117536d8-9ef2-49d2-Ae9e-f5afb330c78f/instance/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/version/ec5f403e-5752-44bb-9ca4-d76375d3ef6a/view"
}
],
"withdrawalHistory": [
{
"instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
"withdrawalStatus": "Withdrawn",
"reason": "some reason",
"withdrawnByUserIdentifier": "10",
"actionTakenDateTime": "2023-05-22T15:40:07.5327879"
},
{
"instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
"withdrawalStatus": "Reinstated",
"reason": "some reason",
"withdrawnByUserIdentifier": "4",
"actionTakenDateTime": "2023-05-22T15:40:11.7514406"
}
]
}Create form instances for a given patient
Route: POST /api/clinicianforms/create/ (Requires authentication) Permission: Create
Description: Create an instance of a form for a given patient
Request
json
{
"patientIdentifier": "a4847fd9-7da1-49da-b5f4-be278dba0730",
"instanceIdentifier": "70b9802a-c7d2-420c-bdc1-0a32b6d06c19",
"formKey": "end-of-life-care",
"formVersion": 1
}We also support an optional property onBehalfOf. This will then create the form under the onBehalfOf user, assuming it passes the implementations authorisation checks implemented in the plugin.
Example:
json
{
"patientIdentifier": "a4847fd9-7da1-49da-b5f4-be278dba0730",
"instanceIdentifier": "70b9802a-c7d2-420c-bdc1-0a32b6d06c19",
"formKey": "end-of-life-care",
"formVersion": 1,
"onBehalfOf": {
"identifier": "user-123",
"type": "user"
}
}Type can be one of the following:
- user
- subject
- system
- external
- subjectProxy
Withdraw a form instance
Route: DELETE /api/patientforms/{PatientId}/instance/{InstanceId}/withdraw (Requires authentication) Permission: Withdraw
Description: Marks a form instance and all its instance versions as being withdrawn and therefore removing it from any API responses unless explicitly requested with the query parameter includeWithdrawn=true
Request
json
{
"reason": "Form created against wrong patient by mistake"
}Reinstate a form instance
Route: PATCH /api/patientforms/{PatientId}/instance/{InstanceId}/reinstate (Requires authentication) Permission: Reinstate
Description: Marks a form instance and all its instance versions as being reinstated and therefore allowing it to be included in any API responses.
Request
json
{
"reason": "Form withdrawn in error"
}Error handling and standard HTTP response codes
HTTP Response Codes are used per standard REST API design. However the most commonly used codes by AireForms are listed below. a Where APIs used a different set or response codes / behaviours these are individually documented with the API
| Code | Description |
|---|---|
200 | Success - The operation to load/save a form or call an API succeded. The response payload will be dependent on the URL/API called |
400 | Bad Request - Occurs if the API request payload (or URL parameters) fail validation or are otherwise malformed |
403 | Forbidden - The User does not have the correct permissions (or is not authenticated), and/or the tenantId or formKey/version configuration does not support the requested operation |
404 | Not Found - The requested URL / API does not exist and/or the tenantId and/or patientId does not exist and/or the formKey/formVersion does not exist or is not in a published state |
500 | Internal Server Error - An error has occured on the server |
503 | Service Unavailable - The server might be re-starting or (more likely) a proxy server cannot contact the service |