This page documents form launch URLs and other APIs of forms4health. Note: in any given deployment not all of these APIs will be availble or directly accessible. Likewise depending on the security model many of these APIs will require authentication and/or will be unavailable.
What you can find on this page:
- Form Load URL Structure
- Form Template APIs
- Form Instance APIs
- Error handling and standard HTTP response codes
Load URL Structure
Non-persisted
Single Pass Forms
Route: GET {tenantId}/SinglePass/{formKey}/{formVersion}
Description: Loads a SinglePass form for the associated tenant
Example: {tenantId}/SinglePass/dental-smile-assessment/1
Single Pass Forms - versionless URL
Typically used to provide a link that will be stable over a long time period. This link might be shared on email, SMS or be embedded in a website or used on a poster / QR code.
Route: GET {tenantId}/SinglePass/{formKey}
Description: forms4health will (if available) launch the highest version form that has a Production publication status. For instance if there is a version 2 form in a status of Production and a version 3 form in a status of Development forms4health will serve the version 2 form. As soon as the version 3 form’s status is changed to Production it will be served via the versionless URL.
Example: {tenantId}/SinglePass/dental-smile-assessment
This feature is useful to allow forms to be upversioned without having to resend communications or change website links - i.e. allows the deploying organisation to make changes that are not externally disruptive.
Form Template APIs
The following APIs are used by a wrapping application to dynamically decide which forms are available for use by users (with the correct permissions) and to provide complete structural and layout infomation of the a particular form template.
Discover what non-persisted style form templates are available (published)
Route: GET /{tenantId}/SinglePass/AvailableForms
Description: Returns a list of forms that are marked as production
Example: /TEST01/SinglePass/AvailableForms
Response
[
{
"name": "FGD Symptom Evaluation",
"key": "fgd-symptom-evaluation",
"versions": [
1,
2
]
},
{
"name": "Patient Dental Smile Assessment",
"key": "dental-smile-assessment",
"versions": [
1
]
}
...
]
Discover what persisted form style templates are available (latest version and published)
Route: GET /api/clinicianforms/availableForms (Requires authentication)
Description: Returns a list of forms limited to the latest creatable version that are marked as production (by default)
Response
[
{
"key": "vte",
"title": "VTE Risk Assessment",
"classification": "Observation"
},
{
"key": "eolc",
"title": "End of Life Care Plan",
"classification": "Plans"
}
...
]
Discover what persisted form style templates are available (published)
Route: GET /api/clinicianforms/allAvailableForms
Description: Returns a list of forms that are marked as production (by default)
Response
[
{
"key": "eolc",
"versionNumber": 2,
"formTitle": "End of life care",
"allowAmend": false,
"classification": "Uncategorised",
"allowSaveDraft": true,
"autoSaveIntervalSeconds": 30,
"allowDiscard": false,
"allowRevoke": true
},
{
"key": "eolc",
"versionNumber": 1,
"formTitle": "End of life care",
"allowAmend": false,
"classification": "Uncategorised",
"allowSaveDraft": true,
"autoSaveIntervalSeconds": 30,
"allowDiscard": false,
"allowRevoke": true
}
]
Get details about a form template
Route: GET /api/v2.0/tenant/{tenantKey}/formdefinition/{formKey}/{formVersion}
Description: Returns a JSON based representation of the entire form.
Example: /api/v2.0/tenant/demo/formdefinition/bmi-reporting/1
Response
{
"key": "bmi-reporting",
"version": 1,
"title": "BMI Reporting",
"allowAmend": false,
"classification": "Uncategorised",
"allowSaveDraft": true,
"autoSaveInteval": 30,
"allowDiscard": false,
"allowRevoke": false,
"buildingBlocks": [
{
"key": "reporting-bmi",
"version": 1,
"xPath": "ReportingBmi",
"sections": [
{
"id": "Section_weight_and_Height",
"xPath": "Section_weight_and_Height",
"controls": [
{
"id": "Unit_type",
"xPath": "Unit_type",
"dataType": "string",
"label": "Unit type",
"hint": "",
"couldHaveValue": true,
"couldHaveMultipleValues": false,
"displayNameXPath": "@displayName",
"otherValueXPath": null
},
{
"id": "Height_meters",
"xPath": "Height_meters",
"dataType": "decimal",
"label": "Height (m)",
"hint": "Height in meters - e.g. 1.81",
"couldHaveValue": true,
"couldHaveMultipleValues": false,
"displayNameXPath": null,
"otherValueXPath": null
},
{
"id": "Height_feet",
"xPath": "Height_feet",
"dataType": "decimal",
"label": "Height (feet)",
"hint": "e.g. 5",
"couldHaveValue": true,
"couldHaveMultipleValues": false,
"displayNameXPath": null,
"otherValueXPath": null
},
{
"id": "Height_inches",
"xPath": "Height_inches",
"dataType": "decimal",
"label": "Height (inches)",
"hint": "e.g. 11 or 11.25",
"couldHaveValue": true,
"couldHaveMultipleValues": false,
"displayNameXPath": null,
"otherValueXPath": null
},
{
"id": "Weight_kg",
"xPath": "Weight_kg",
"dataType": "decimal",
"label": "Weight (kg)",
"hint": "",
"couldHaveValue": true,
"couldHaveMultipleValues": false,
"displayNameXPath": null,
"otherValueXPath": null
},
{
"id": "Weight_pounds",
"xPath": "Weight_pounds",
"dataType": "decimal",
"label": "Weight (pounds)",
"hint": "",
"couldHaveValue": true,
"couldHaveMultipleValues": false,
"displayNameXPath": null,
"otherValueXPath": null
}
],
"repeats": []
},
{
"id": "Section_BMI",
"xPath": "Section_BMI",
"controls": [
{
"id": "BMI",
"xPath": "BMI",
"dataType": "decimal",
"label": "BMI",
"hint": "",
"couldHaveValue": true,
"couldHaveMultipleValues": false,
"displayNameXPath": null,
"otherValueXPath": null
},
{
"id": "Weight_appropriate",
"xPath": "Weight_appropriate",
"dataType": "string",
"label": "Weight appropriate",
"hint": "",
"couldHaveValue": true,
"couldHaveMultipleValues": false,
"displayNameXPath": null,
"otherValueXPath": null
}
],
"repeats": []
}
]
}
]
}
Get details about the Un-persisted data format (when used in conjunction with a Delivery Channel)
Route: GET /api/v2.0/tenant/{tenantKey}/formschema/{formKey}/{version}
Description: Returns an auto generated XML Schema showing the structure of data that would be sent via the un-persisted forms delivery channel
Example: api/v2.0/tenant/demo/formschema/form-invite/1
Response
<xsd:schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:simpleType name="xf-decimal">
<xsd:union>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:length value="0" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType>
<xsd:restriction base="xsd:decimal" />
</xsd:simpleType>
</xsd:union>
</xsd:simpleType>
<xsd:simpleType name="xf-integer">
<xsd:union>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:length value="0" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType>
<xsd:restriction base="xsd:integer" />
</xsd:simpleType>
</xsd:union>
</xsd:simpleType>
...
<xsd:element name="PatientForm">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="GenericFormInviteLauncherPreamble">
<xsd:complexType>
<xsd:sequence minOccurs="0">
<xsd:element name="InvitePreamble">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Preamble" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="templateId" type="xsd:string" use="optional" />
</xsd:complexType>
</xsd:element>
...
</xsd:sequence>
<xsd:attribute name="token" type="xsd:string" use="optional" />
<xsd:attribute name="transaction-id" type="xsd:string" use="optional" />
</xsd:complexType>
</xsd:element>
</xsd:schema>
Form Instance APIs
These APIs are only applicable for forms4health 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
[
{
"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
[
{
"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: Create
Description: Retrieves the history of an instance.
Example response
{
"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
{
"patientIdentifier": "a4847fd9-7da1-49da-b5f4-be278dba0730",
"instanceIdentifier": "70b9802a-c7d2-420c-bdc1-0a32b6d06c19",
"formKey": "end-of-life-care",
"formVersion": 1
}
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
{
"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
{
"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 forms4health 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 |
