Help Center
    Follow

    Forms API Overview

    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:

    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

    You can get this resource directly using the API with a cURL

    curl -X GET --header 'Accept: application/json;charset=UTF-8' 
    'https://secure.surecloud.com/restful/v1/forms/paths?token=<userAPIToken>'

    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.

    For further information on this model’s properties see our Swagger documentation.

    From the list of Forms it is possible to search for the Forms of interest looking for known data to help identify the required Form. Currently, CTRL + F searching for known information is a relatively quick means of locating the required Form.

    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' 
    'https://secure.surecloud.com/restful/v1/forms/<questionnaireKey>/data?token=<userAPIToken>'

    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.

     

     

    Was this article helpful?
    0 out of 0 found this helpful

    Comments

    Further Questions?