Page tree
Skip to end of metadata
Go to start of metadata

The following table provides a quick reference to the most frequently used endpoints of REST API.

URISummary
GET /form-treeLists all Form definitions in a hierarchy
Folder API (Form Definition Collection)
GET /folder/{id}Lists the content of a folder with given ID
PUT /folder/{id}Updates the details of a folder with given ID
POST /folder/{id}Creates a new folder in a parent folder with given ID
DELETE /folder/{id}Deletes folder with given ID
GET /folder/{id}/exportGenerates archive of all definitions located in a folder with given ID
Form API (Form Definition)
GET /form/{id}Provides details of a Form with given ID
DELETE /form/{id}Deletes Form with given ID
POST /form/{id}/publishPublishes Form with given ID
PUT /form/{id}/versionCreates a new unpublished version of a Form with given ID
DELETE /form/{id}/versionDeletes a draft version of a Form with given ID
GET /form/{id}/exportGenerates definition archive of a Form with given ID
GET /form/{id}/campaignsLists all campaigns of a Form with given ID
Campaign API (Form Data Collection) (see also Managing Submitted Data)
GET /campaign/{id}Provides details of a campaign with given ID
DELETE /campaign/{id}Deletes campaign and all campaign records
POST /campaign/{id}/stopStops the campaign with given ID
POST /campaign/{id}/resumeResumes the campaign with given ID
DELETE /campaign/{id}/clearDeletes all data (session records) that belong to the campaign with given ID
GET /campaign/{id}/sessionsLists sessions that belong to the campaign with given ID
Session API (Form Data)
GET /session/{id}Provides details of a session with given ID
GET /session/{id}/attachment/{fid}Fetches session file attachment for a field with given field ID
POST /session/{id}/stateAssigns new runtime state to a session with given ID
GET /session/{id}/xslfo/{name}Fetches the result of a named XSLFO transformation for a session with given ID, e.g. PDF document

GET /form-tree

Top of the page

Use this endpoint to list a full hierarchy of Form definitions.

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/form-tree

Sample Response

The response below is received for the following hierarchy displayed in SmartForms Administration Console:

{
   "_meta":{
      "success":true,
      "errors":null,
      "requestId":"023c49a4-7f1b-4212-be87-2d58cc3dee9f"
   },
   "data":{
      "tree":[
         {
            "id":"root",
            "name":"My Forms",
            "folders":[
               {
                  "id":"65b27518-6888-4b5c-b92a-e63c36dbea68",
                  "name":"Communication Forms",
                  "folders":[

                  ],
                  "forms":[
                     {
                        "id":"cd220558-6697-4a16-a565-587866ab1bb9",
                        "name":"Contact Us"
                     },
                     {
                        "id":"46e4d733-d0c7-407f-a734-f2a52d708fe2",
                        "name":"Customer compliment"
                     }
                  ]
               },
               {
                  "id":"a84a866e-5048-4a55-8518-2440cca4b836",
                  "name":"Employee",
                  "folders":[
                     {
                        "id":"ac3093c0-53dc-4eb1-98d9-324508dee912",
                        "name":"HR",
                        "folders":[

                        ],
                        "forms":[
                           {
                              "id":"cabcdd00-0ba7-4920-a26b-9f6181212604",
                              "name":"Annual Leave"
                           },
                           {
                              "id":"bfa96ba1-2d68-496f-9e5d-f59eadb2ca10",
                              "name":"Job Application (Internal)"
                           }
                        ]
                     }
                  ],
                  "forms":[

                  ]
               }
            ],
            "forms":[

            ]
         }
      ],
      "selected_form_id":null
   }
}

Response Properties

PropertyDescription
treeTop element that contains the top 'root' folder
Folder properties
idA unique ID (UUID) of a folder
nameName of a folder
foldersAn array of child folders
formsAn array of forms located in the folder
Form properties
idA unique ID (UUID) of a form
nameName of a form
Top of the page


GET /folder/{id}

Top of the page

Use this endpoint to check the existence of a folder and its name.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a folder

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/folder/65b27518-6888-4b5c-b92a-e63c36dbea68

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"bcd11b95-745f-4ee8-bd78-2ba0c42c2979"
   },
   "data":{  
      "id":"65b27518-6888-4b5c-b92a-e63c36dbea68",
      "name":"Communication Forms"
   }
}

Response Properties

PropertyDescription
idA unique ID (UUID) of a folder
nameName of a folder

Response Codes

CodeDescription
200OK
400Bad request, folder ID is not a UUID number
404Folder record not found
Top of the page

PUT /folder/{id}

Top of the page

Use this endpoint to change the name of a folder.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a folder
Data
nameNew name of a folder

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X PUT -d @data.json https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/folder/65b27518-6888-4b5c-b92a-e63c36dbea68

Sample Request Data

{
	"name": "New folder name"
}


Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"56d34299-199a-42ab-a6da-7f26603bddda"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, folder has been renamed
400Bad request, folder ID is not a UUID number
404Folder record not found
Top of the page

POST /folder/{id}

Top of the page

Use this endpoint to create a subfolder.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a folder, or 'root' for root folder
Data
nameName of a folder to be created

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X POST -d @data.json https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/folder/65b27518-6888-4b5c-b92a-e63c36dbea68

Sample Request Data

{
	"content": "Subfolder name"
}

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"3cf555d4-7db1-4fde-b52e-ebb9e2c6faa2"
   },
   "data":{  
      "id":"77ac6220-1a0c-48e8-a6e8-84a4acd0830e",
      "name":"SubFolder Name"
   }
}

Response Properties

PropertyDescription
idA unique ID (UUID) of a created folder
nameName of a folder

Response Codes

CodeDescription
202Accepted, folder has been created
400Bad request, parent folder ID is not a UUID number or 'root' for root parent folder
404Folder record not found
409Conflict, duplicate record: folder with this name already exists
Top of the page

DELETE /folder/{id}

Top of the page

Use this endpoint to delete a subfolder.

Folder cannot be deleted if it contains parent folders or forms.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a folder

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X DELETE https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/folder/77ac6220-1a0c-48e8-a6e8-84a4acd0830e

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"a7e19984-fc51-48c7-88f2-f811de500b6d"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, folder has been deleted
400Bad request, parent folder ID is not a UUID number
404Folder record not found
409Conflict, permission is not granted: folder contains subfolders or forms
Top of the page

GET /folder/{id}/export

Top of the page

Use this endpoint to export all form definitions located in this folder and subfolders.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a folder to be exported, or 'root' for root folder

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -X GET --output "folder.far" -v -i https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/folder/65b27518-6888-4b5c-b92a-e63c36dbea68/export

Sample Response

< Content-Length: 7247
< Content-Type: application/octet-stream
< Content-Disposition: filename=smartforms.folder.FolderName.far


The output of this response is a newly created file with the name as specified in --output option, "folder.far" in this case. You can check the content of this file with any ZIP program, see the sample content below:

Response Headers

PropertyDescription
Content-LengthSize of the file
Content-Type

Type of the file content:

  • plain/text, if the response code is not 200
  • application/octet-stream, if the response code is 200
Content-Disposition

Name of the file:

  • error.txt, if the response code is not 200
  • smartforms.folder.{folder-name}.far, if the response code is 200

Response Codes

CodeDescription
200OK
400Bad request, folder ID is not a UUID number or not 'root'
404Folder record not found
Top of the page


GET /form/{id}

Top of the page

Use this endpoint to get the current details of a form.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a form

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/form/cabcdd00-0ba7-4920-a26b-9f6181212604

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"5c4e4be5-ff3a-44cd-b345-ab6dbe18ba79"
   },
   "data":{  
      "id":"cabcdd00-0ba7-4920-a26b-9f6181212604",
      "name":"Annual Leave",
      "date_created":"2017-12-06T18:59:04+11:00",
      "description":"Annual leave application",
      "parent_folder_id":"ac3093c0-53dc-4eb1-98d9-324508dee912",
      "published_form":{  
         "build_status":"READY",
         "build_errors":[  
         ],
         "date_created":"2017-12-06T18:59:04+11:00",
         "published":true,
         "date_published":"2017-12-08T14:45:21+11:00",
         "version":1,
         "release_form_id":"1d665c65-e14c-4dc2-b003-0815968d3d57"
      },
      "draft_form":{  
         "build_status":"READY",
         "build_errors":[  
         ],
         "date_created":"2017-12-08T14:45:23+11:00",
         "published":false,
         "date_published":null,
         "version":2,
         "release_form_id":"b413b579-ff50-409f-9969-6595c76b40e1"
      },
      "build_status":"READY",
      "build_errors":[  
      ]
   }
}

Response Properties

PropertyDescription
idA unique ID (UUID) of a form
nameName of a form
descriptionDescription of a form
date_createdDate when the form was created initially
parent_folder_idAn ID of an immediate parent folder
build_status

Status of a form build, where the possible values are:

  • BLANK,
  • IN_PROGRESS,
  • READY,
  • FAILED
build_errorsList of error messages, if the build_status is FAILED
published_formDetails of a published version of a form, null if a form has never been published
draft_versionDetails of an unpublished version of a form, null if no unpublished form version exists
Form Version Properties
release_form_idA unique ID (UUID) of a version of a form (published or unpublished)
versionA consequtive number assigned to the version of a form
date_createdA date when form version has been created
published'true' for published form version, 'false' for unpublished
date_publishedA date when form version was published, null for unpublished form version

Response Codes

CodeDescription
200OK
400Bad request, form ID is not a UUID number
404Form record not found
Top of the page

DELETE /form/{id}

Top of the page

Use this endpoint to delete a form and related data.

Danger !

Please be aware that this action will remove form definition, form campaigns and all data submitted by users.

Deleted data cannot be recovered.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a form

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X DELETE https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/form/cabcdd00-0ba7-4920-a26b-9f6181212604

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"60a45f62-13e6-4b1d-8c6f-79a8efa4c5ea"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, form has been deleted
400Bad request, form ID is not a UUID number
404Form record not found
Top of the page


POST /form/{id}/piblish

Top of the page

Use this endpoint to publish a form version.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a form
Data
release_notesOptional, description of the changes made, up to 512 characters.
user_idOptional, ID of a user who has authorised/executed the release of a form, up to 64 characters.

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X POST -d @data.json https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/form/cabcdd00-0ba7-4920-a26b-9f6181212604/publish

Sample Request Data

{
	"release_note": "Added field 'user.midddle-name'",
	"user_id": "jdoe"
}

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"b29be6ff-c3ba-4e3d-9324-f86d86f39b27"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, form has been published
400Bad request, form ID is not a UUID number
404Form record not found
409Conflict, form is already published, i.e. no unpublished form version has been found
Top of the page

PUT /form/{id}/version

Top of the page

Use this endpoint to create a new unpublished form version.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a form

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X PUT https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/form/cabcdd00-0ba7-4920-a26b-9f6181212604/publish

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"6091d079-c49b-4f33-9f93-e1acc0922265"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, new unpublished version of a form has been created
400Bad request, form ID is not a UUID number
404Form record not found
409Conflict, unpublished form version already exists
Top of the page

DELETE /form/{id}/version

Top of the page

Use this endpoint to delete an unpublished form version.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a form

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X DELETE https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/form/cabcdd00-0ba7-4920-a26b-9f6181212604/publish

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"7943322e-7e14-48d3-aeaf-fd7a96fdef8d"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, an unpublished version of a form has been deleted
400Bad request, form ID is not a UUID number
404Form record not found
409Conflict, unpublished form version does not exist
Top of the page

GET /form/{id}/export

Top of the page

Use this endpoint to export definition of the latest (published or unpublished) form version.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a form to be exported

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -X GET --output "folder.far" -v -i https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/folder/bfa96ba1-2d68-496f-9e5d-f59eadb2ca10/export

Sample Response

< Content-Length: 7161
< Content-Type: application/octet-stream
< Content-Disposition: filename=smartforms.form.Job_Application_(Internal).far


The output of this response is a newly created file with the name as specified in --output option, "form.far" in this case. You can check the content of this file with any ZIP program, see the sample content below:

Response Headers

PropertyDescription
Content-LengthSize of the file
Content-Type

Type of the file content:

  • plain/text, if the response code is not 200
  • application/octet-stream, if the response code is 200
Content-Disposition

Name of the file:

  • error.txt, if the response code is not 200
  • smartforms.form.{form-name}.far, if the response code is 200

Response Codes

CodeDescription
200OK
400Bad request, form ID is not a UUID number
404Form record not found
Top of the page


GET /form/{id}/campaigns

Top of the page

Use this endpoint to get the list of campaigns of a form.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a form

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/form/cabcdd00-0ba7-4920-a26b-9f6181212604/campaigns

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"b73096a2-e55d-4529-8f27-a0a847162171"
   },
   "data":[  
      {  
         "id":"df870492-06dd-408d-baf0-3d2ca545a01e",
         "name":"Job Application (Internal)",
         "form_id":"bfa96ba1-2d68-496f-9e5d-f59eadb2ca10",
         "date_started":"2017-12-06T19:00:22+11:00",
         "date_created":"2017-12-06T19:00:22+11:00",
         "date_completed":null,
         "status":"LIVE",
         "records_submitted":0,
         "records_total":0
      },
      {  
         "id":"e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a",
         "name":"test",
         "form_id":"bfa96ba1-2d68-496f-9e5d-f59eadb2ca10",
         "date_started":null,
         "date_created":"2017-12-06T19:00:23+11:00",
         "date_completed":null,
         "status":"TEST",
         "records_submitted":0,
         "records_total":0
      }
   ]
}

Response Properties

PropertyDescription
idA unique ID (UUID) of a campaign
nameName of a campaign
date_startedA latest date when the campaign was started, null for TEST campaign
date_createdA date when the campaign was created initially
date_completedA date when the campaign has been stopped, null if campaign is not stopped
status

Status of a campaign, where the possible values are:

- TEST: campaign is running in test mode;

- LIVE: campaign is running in production mode;

- COMPLETED: campaign is stopped.

records_submittedA count of form sesssions completed
date_publishedA total count of form sessions, completed and in progress

Response Codes

CodeDescription
200OK
400Bad request, form ID is not a UUID number
404Form record not found
Top of the page


GET /campaign/{id}

Top of the page

Use this endpoint to get details of a campaign.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a campaign

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/campaign/e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"42a787f4-a4f7-4fb9-b9dd-3e2b9097e20c"
   },
   "data":{  
      "id":"e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a",
      "name":"test",
      "form_id":"bfa96ba1-2d68-496f-9e5d-f59eadb2ca10",
      "date_started":null,
      "date_created":"2017-12-06T19:00:23+11:00",
      "date_completed":null,
      "status":"TEST",
      "records_submitted":3,
      "records_total":4
   }
}

Response Properties

PropertyDescription
idA unique ID (UUID) of a campaign
nameName of a campaign
date_startedA latest date when the campaign was started, null for TEST campaign
date_createdA date when the campaign was created initially
date_completedA date when the campaign has been stopped, null if campaign is not PRODUCTION
status

Status of a campaign, where the possible values are:

- TEST: campaign is running in test mode;

- LIVE: campaign is running in production mode;

- COMPLETED: campaign is marked as stopped.

records_submittedA count of form sesssions completed
date_publishedA total count of form sessions, completed and in progress

Response Codes

CodeDescription
200OK
400Bad request, campaign ID is not a UUID number
404Campaign is not found
Top of the page

DELETE /campaign/{id}

Top of the page

Use this endpoint to delete a campaign and related data.

Test campaigns cannot be deleted.

Production campaigns cannot be deleted, change status of production campaign to stopped (using POST /campaign/{id}/stop or via Administration Console) and then delete.


Danger !

Please be aware that this action will remove form campaign and all campaign data submitted by users.

Deleted data cannot be recovered.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a campaign

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X DELETE https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/campaign/e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"c05cbdab-0fc1-411c-9970-4536acbe150d"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, campaign has been deleted
400Bad request, form ID is not a UUID number
404Campaign is not found
409Conflict, deletion of campaign has been rejected, Production or Test campaigns cannot be deleted
Top of the page

POST /campaign/{id}/stop

Top of the page

Use this endpoint to stop a production campaign.

TEST campaigns cannot be stopped.


Warning !

Please be aware that this action will disallow users to start, continue and submit forms.

Stopped campaign can be resumed at any time.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a campaign

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X POST https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/campaign/e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a/stop

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"653a1b28-8a5d-492b-984b-4e4fd2e2d125"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, campaign has been stopped
400Bad request, form ID is not a UUID number
404Campaign is not found
409Conflict, stopping of campaign has been rejected, Stopped or Test campaigns cannot be stopped
Top of the page

POST /campaign/{id}/resume

Top of the page

Use this endpoint to resume a production campaign.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a campaign

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X POST https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/campaign/e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a/resume

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"92776582-e824-4624-aa80-c664dd56d158"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, campaign has been resumed
400Bad request, form ID is not a UUID number
404Campaign is not found
409Conflict, action has been rejected, Production and Test campaigns cannot be resumed
Top of the page

DELETE /campaign/{id}/clear

Top of the page

Use this endpoint to delete form session records from this campaign.

Records from Production campaigns cannot be deleted, change status of Production campaign to Stopped (using POST /campaign/{id}/stop or via Admin Console) and then apply this action.


Danger!

Please be aware that deleted data cannot be recovered.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a campaign

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X DELETE https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/campaign/e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a/clear

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"61ac9cd0-3f3d-4021-9c93-a422f2bac6c8"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, campaign records have been deleted
400Bad request, form ID is not a UUID number
404Campaign is not found
409Conflict, deletion of campaign records has been rejected, records of Production campaigns cannot be deleted
Top of the page


GET /campaign/{id}/sessions?{query}

Top of the page

Use this endpoint to list sessions of a campaign.

This data can be further explored iteratively using GET /session/{id}?{query} endpoint.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a campaign

Request Query Parameters

ParameterDescriptionDefault Value

include-in-progress-sessions

If 'true' include in-progress sessions, sessions that have been started by users but not submitted yetfalse
include-submitted-sessionsIf 'false', do not include submitted sessionstrue
filter-by-stateLimit search only to those sessions which have runtime states included in a comma-separated list-

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/campaign/e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a/sessions

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"8e53a5eb-86b5-4392-a16a-205f3591acc9"
   },
   "data":[  
      "305cce4a-c16f-44b6-b5db-8acfbec2c8d2",
      "0e3e984b-6bee-4a21-b08f-478e29d71948",
      "5fa66ac7-7e30-4b52-a7fc-ad869346ae68"
   ]
}

Response Properties

PropertyDescription
dataList of unique IDs (UUID) of form sessions

Response Codes

CodeDescription
200OK
400Bad request, campaign ID is not a UUID number
404Campaign is not found
Top of the page


GET /session/{id}?{query}

Top of the page

Use this endpoint to get form session details.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a campaign

Request Query Parameters

ParameterDescription

return

Optional comma-separated list field names to be fetched.

Field name in a query can be either:

  1. An exact field name, or
  2. A 'starts-with' field name filter expression, it it contains a '*' as a wild character, e.g.:
    pattern 'person.*' will bring all fields where field names start with 'user.', e.g. 'person.first-name', 'person.address.street.no', 'person.phone.mobile', etc
    pattern '*' will bring all form fields


Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/session/305cce4a-c16f-44b6-b5db-8acfbec2c8d2?return=user.*

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"8c895099-57a0-4aeb-9a78-28d3f2706645"
   },
   "data":{  
      "sessionId":"f5963e7c-590d-447e-8b06-5aa4695a8038",
      "campaignId":"e9fe9b7c-32b2-4ab9-be46-2e7fd6d63a3a",
      "formTypeId":"bfa96ba1-2d68-496f-9e5d-f59eadb2ca10",
      "formId":"bf20c606-56fe-4fc6-987f-ed6a9d0f615f",
      "trackingCode":"FC4ODNXS",
      "status":"COMPLETED",
      "dateCreated":"2017-12-09T19:46:06+1100",
      "dateSubmitted":"2017-12-09T19:46:38+1100",
      "referenceCode":"384cd0b4-9a3c-4fdf-b459-6ff691b7fce9",
      "runtimeState":"NEW",
      "fields":[  
         {  
            "name":"user.first.name",
            "id":"7974d9cc-9869-450a-803c-54c704caafac",
            "cloneIndex":0,
            "validated":true,
            "hidden":false,
            "valueType":"TEXT",
            "value":"John"
         },
         {  
            "name":"user.last.name",
            "id":"e0cbca60-847e-4f54-ae3e-b27be285de5f",
            "cloneIndex":0,
            "validated":true,
            "hidden":false,
            "valueType":"TEXT",
            "value":"Legend"
         },
         {  
            "name":"user.sex",
            "id":"ba16e8a4-4b83-4a41-a327-464ee71d82e5",
            "cloneIndex":0,
            "validated":true,
            "hidden":false,
            "valueType":"TEXT",
            "value":"male"
         },
         {  
            "name":"user.resume",
            "id":"ad8a822b-b529-4749-8b06-78f2eecf2eb3",
            "cloneIndex":0,
            "validated":true,
            "hidden":false,
            "valueType":"FILE_ATTACHMENT",
            "value":"resume.pdf;1227240"
         }
      ]
   }
}

Response Properties

PropertyDescription
sessionIdUnique ID (UUID) of a session
campaignIdUnique ID (UUID) of a campaign this session is running in
formTypeIdUnique ID (UUID) of a form this session is running
formIdUnique ID (UUID) of a form version this session is running
trackingCodeUnique code assigned to this session
status

Status of this session, possible values are:

  • STARTED,
  • SUSPENDED,
  • COMPLETED,
  • DELETED
dateCreatedA datetime when this form has been started
dateSubmittedA datetime when this form has been submitted, null if the session is still in progress
referenceCodeA unique internal reference ID (UUID) of this session
runtimeStateA runtime state of this session
fieldsAn array of field details
Field Properties
nameName of a field
idA session-unique ID (UUID) of the field
cloneIndexA clone number, a positive integer when field was defined is a part of a clonable group and form session contains more than one clones of a field with the same name
validatedA flag that indicates whether this field has passed form validation
hiddenA flag that indicates whether this field is visible on session form
valueType

Type of a field valuie, possible value types are:

  • TEXT,
  • INTEGER,
  • FLOAT,
  • FILE_ATTACHMENT,
  • DATE,
  • TIME_OF_DAY,
  • DATETIME,
  • HTML
valueValue of a field

Response Codes

CodeDescription
200OK
400Bad request, session ID is not a UUID number
404Session is not found
Top of the page

GET /session/{id}/attachment/{fid}

Top of the page

Use this endpoint to download file attachment.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a session
fidAn ID of a field that contains file attachment

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -X GET --output "attachment" -v -i https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/session/625b8ae8-4ce4-4e6c-96a2-02717436b8eb/attachment/07b27518-6888-4b5c-b92a-e63c36dbea68

Sample Response

< Content-Length: 1227240
< Content-Type: application/octet-stream
< Content-Disposition: filename=resume.pdf


The output of this response is a newly created file with the name as specified in --output option, "attachment" in this case. When downloading the file the following response headers shall be used to get information abouth the downloaded file.

Response Headers

PropertyDescription
Content-LengthSize of the file
Content-Type

Type of the file content:

  • plain/text, if the response code is not 200
  • application/octet-stream, if the response code is 200
Content-Disposition

Name of the file:

  • error.txt, if the response code is not 200
  • blank.txt, if the response code is 204
  • attached filename, if the response code is 200

Response Codes

CodeDescription
200OK
204No content, field does not have file attachment
400Bad request, session ID or field ID is not a UUID number
404Session is not found
Top of the page


POST /session/{id}/state?{stateName}

Top of the page

Use this endpoint to assign a custom runtime state name to a session record.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a session
stateNameA new runtime state name to be assigned to a session record

Custom runtime state can be used in REST API as a session query parameter filter-by-state in GET /campaign/{id}/sessions query.

If state name is assigned to DELETED, the session record will be scheduled for an immediate deletion.

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -H "Content-Type:application/json" -X POST https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/session/05302c2c-2976-4b29-b576-ebcced860f18/state?stateName=PROCESSED

Sample Response

{  
   "_meta":{  
      "success":true,
      "errors":null,
      "requestId":"00f6aa89-d3b4-445f-8399-5f22e2a71d73"
   },
   "data":null
}

Response Codes

CodeDescription
202Accepted, state has been assigned
400Bad request, session ID is not a UUID number
400Bad request, stateName is not provided or too long (over 40 characters)
404Session record not found
Top of the page

GET /session/{id}/xslfo/{name}

Top of the page

Use this endpoint to download the result of XSLFO transformation, i.e. PDF document.

Request Properties

PropertyDescription

id

A unique ID (UUID) of a session
nameName of XSLFO transformation

Sample Request

curl -H "X-API-Token:CLIENT-ID:API-TOKEN" -X GET --output "auto.pdf" -v -i https://aus.001.smartfor.ms/smartform-runtime-portlet/api/v1/session/625b8ae8-4ce4-4e6c-96a2-02717436b8eb/xslfo/auto

Sample Response

< Content-Length: 1577634
< Content-Type: application/octet-stream
< Content-Disposition: filename=auto.pdf


The output of this response is a newly created file with the name as specified in --output option, "auto.pdf" in this case. When downloading the file the following response headers shall be used to get information about the downloaded file.

Response Headers

PropertyDescription
Content-LengthSize of the file
Content-Type

Type of the file content:

  • plain/text, if the response code is not 200
  • application/octet-stream, if the response code is 200
Content-Disposition

Name of the file:

  • error.txt, if the response code is not 200
  • blank.txt, if the response code is 204
  • pdf filename, if the response code is 200

Response Codes

CodeDescription
200OK
400Bad request, session ID is not a UUID number
404Session is not found
404XSLFO name is not found
500Error in generating XSLFO transformation
Top of the page

  • No labels