Overview
Using SureCloud’s REST API, you can retrieve both the values and structural information for your Forms.
To access any of the services on the API, a User must be authenticated to the SureCloud Platform. Two methods are available for this and are explained here.
All available services require an Accept header of 'application/json' to be sent.
'Accept: application/json'
Within this guide, we’ll explore how to:
- Find the Form you are looking for
- Retrieve the data stored for the Form
- Update the Form’s data
- Add new sections to the Form
SureCloud's RESTful API also uses Swagger documentation and try out many of the features. This documentation can be found at https://secure.surecloud.com/swaggerDocumentation
Within this documentation you can find all available functions, request information, HTTP status explanations, model explanations and much more.
Listing available Forms
To view a list of available forms, make a HTTP GET request to your account’s Form Paths resource.
https://secure.surecloud.com/restful/v1/forms/paths
With no parameters set this call will return a list of all available forms. In order to return a specific form or forms you can use some optional filter parameters:
- path = The folder containing the form or forms. For example: /FolderA/FolderB.
- questionnaireKey = The unique key of the form you wish to request. For example: 12345678.
- questionnaireTitle = The name of the form you wish to request. For example: Example form name.
One or more of these filter query parameters can be applied to the HTTP GET request.
https://secure.surecloud.com/restful/v1/forms/paths?path=<path>
https://secure.surecloud.com/restful/v1/forms/paths?questionnaireTitle=<questionnaireTitle>&path=<path>
https://secure.surecloud.com/restful/v1/forms/paths?path=<path>&questionnaireKey=<questionnaireKey>&questionnaireTitle=<questionnaireTitle>
You can get this resource directly using the API with a cURL (no filter)
curl -X GET --header 'Accept: application/json;charset=UTF-8'
--header 'Authorization: Bearer <JWTHere>'
'https://secure.surecloud.com/restful/v1/forms/paths'
or with a cURL (using a questionnaireKey filter)
curl -X GET --header 'Accept: application/json;charset=UTF-8'
--header 'Authorization: Bearer <JWTHere>'
'https://secure.surecloud.com/restful/v1/forms/paths?questionnaireKey=12345678'
or alternatively use our Swagger documentation’s “Try it out!” feature.
Result
Making a successful call to the Form Paths resource will result in a Response Code of 200, and return a body similar to the example below.
[
{
"standardKey": 123,
"questionnaireKey": 1,
"path": /Initial Folder ",
"questionnaireTitle": "Example first form",
"templateTitle": "Basic Form",
"links": [
{
"rel": "data",
"href": "https://secure.surecloud.com/restful/v1/forms/1/data"
}
]
},
...,
{
"standardKey": 123,
"questionnaireKey": 2,
"path": "/Initial Folder",
"questionnaireTitle": "Example second form",
"templateTitle": "Basic Form",
"links": [
{
"rel": "data",
"href": "https://secure.surecloud.com/restful/v1/forms/2/data"
}
]
}
]
This JSON represents all the Forms the authenticated user has access to, with information regarding the location, and identification of those Forms. Using a filter with the call will ensure that the JSON only contains Forms that adhere to the filter criteria.
For further information on this model’s properties see our Swagger documentation.
If you return a large list of Forms it is possible to narrow the dataset by using an optional filter parameter in your call (see above).
Each Form Path model contains the HATEAOS link for the data for that Forms e.g.
{
"rel": "data",
"href": "https://secure.surecloud.com/restful/v1/forms/2/data"
}
Which allows you then to fetch or update the data held within the Form.
Retrieving data for a Form
To view the data stored on a given Form, it is possible to go direct from the Form Path supplied HATEOAS link for the “data” relationship, or to use the Form Data end point with a HTTP GET request if the questionnaireKey is already known.
https://secure.surecloud.com/restful/v1/forms/<questionnaireKey>/data
You can get this resource directly using the API with a cURL
curl -X GET --header 'Accept: application/json;charset=UTF-8'
--header 'Authorization: Bearer <JWTHere>'
'https://secure.surecloud.com/restful/v1/forms/<questionnaireKey>/data'
Additionally you can use our Swagger documentation to “Try it out!”.
Result
Making a successful call to the Form Data end point will result in a Response Code of 200, and return a body containing the QuestionnaireResponses model.
This model will be a structural representation of the Form found within SureCloud and contain the response value of each response.
At a high level the response will be similar to the below example.
{
"questionnaireKey": 0,
...
"sections": [
{
"description": "string",
"identifier": "string",
...
"responses": [
{
"key": 0,
"mandatory": true,
"title": "string",
"type": "REFERENCE",
...
"value": {
<JSON representation of the value and type>
}
}
],
"sections": [
{
<sub sections>
}
]
}
]
}
Refer to the Swagger documentation for model property explanations and “Try it out!” functionality.
Modifying Responses on a Form
Making a HTTP POST request to the Form Data end point will allow the responses for the Form to be updated.
https://secure.surecloud.com/restful/v1/forms/data
The service allows for the entire Form to be posted back with the modified responses, or a smaller subset of just the changed Responses. This Form (or subset) should be passed to the endpoint within the Body of the request, for example:
{
"sections": [
{
"key": 123,
"responses": [
{
"key": 321,
"value": {
"value": "Example new Value",
"type": "TEXT"
}
}
]
}
],
"questionnaireKey": 11111
}
The section the Questionnaire, Section and Response must be identified by their corresponding keys, and then the value can be updated.
Adding a new Section to a Form
The Form Data service also allows for new Sections to be added to Insertable Sections. To do this make a HTTP POST to the Form Data end point.
https://secure.surecloud.com/restful/v1/forms/data
Similarly, when changing Response Values on a Form, the entire Form can be passed to the end point or a subset of just the additional Sections (or changed Responses at the same time). Once again, the required changes should be passed as the Body of the request.
{
"sections": [
{
"insert": "true",
"key": 123,
"responses": [
{
"key": 321,
"value": {
"value": "This will a new response, in a new section.",
"type": "TEXT"
}
}
]
}
],
"questionnaireKey": 11111
}
The new Section will be created after the given section in the Section.Key value. Default, or computed values will be applied for “free” on the section, so there is no need to supply Response values for those.
Useful links:
Comments