XForms APIs

(for Developers and Software Integrations)

XForms uses RESTful APIs to communicate between its mobile apps, reporting and admin web app, and other external systems.   

***NOTE*** Our documentation is a work in progress and will be updated and improved regularly as the platform matures.

Example Use Case

With the XForms APIs, you could—for example—use XForms solely for field data capture, and then extract that data out of XForms for insertion into your existing enterprise reporting dashboard software.  This is a perfectly normal use case for XForms. 

Here’s what you would do to make this work

  • Build your forms using the XForms Designer.  If these forms use listboxes with reference values, then you would also build reference lists in XForms
  • Populate and update the reference lists in XForms programmatically
  • Extract saved forms programmatically.  You can even extract images (including the draw layer), signatures, tables, and PDF versions of the saved forms.

How to Update a Reference-List

To update any type of document, such as Form, Template, and Reference-List, you must follow the following 3 steps:

  1. Authenticate and obtain the Access-Token
  2. Get Reference-list ID (if not available)
  3. Read the reference-list
  4. Write the update reference-list

Obtain Auth-Token

Before calling any endpoint in XForms API, you would need to obtain an access token. Then the Access-Token needs to be sent along with any other requests.

Token
URL https://api.xformsweb.com/identity/token
Request Type POST
Request Body {

"email": "string",
"password": "string",
"client": "api.client"
}
Response Body {

"access_token": "string",
"expires_in": 10800, (number of seconds till expiration of the token)
"token_type": "Bearer"
}

Comments The value of access_token must be preserved and used for subsequent calls

Get Reference-List’s ID

The reference-list can be downloaded using its ID. If the ID not available, we can get a list of existing reference-lists with their IDs first

List of Reference-Lists
URL https://api.xformsweb.com/contents/type/refList?select=id,name
Header Authorization: Bearer <access-token>
Request Type GET
Request Body
Response Body [
{
"id": "9488501c-c27b-4b14-9890-8cfff3bd3349",
"name": "Projects"
},
...
]

Comments By adding the “select” parameter in the URL above, you can request only certain fields

from the document.

Get Reference-List by ID

If the reference-list ID is available, the full document can be retrieved by calling the get by ID endpoint

Reference-List by ID
URL https://api.xformsweb.com/contents/9488501c-c27b-4b14-9890-8cfff3bd3349
Request Type GET
Header Authorization: Bearer <access-token>
Request Body
Response Body {

"id": "9488501c-c27b-4b14-9890-8cfff3bd3349",
"name": "Projects",
"items": [
{
"name": "FRCA"
},
{
"name": "Kane"
},
...
]
}

Updating Reference-List

The updated reference-list can be uploaded to the server by calling the Put endpoint.
Please note that only the “items” part of the reference-list can be updated. Changing name or ID might break the link of the reference list to the forms.

Reference-List by ID
URL https://api.xformsweb.com/contents/9488501c-c27b-4b14-9890-8cfff3bd3349
Request Type PUT
Header Authorization: Bearer <access-token>
Request Body {

"id": "9488501c-c27b-4b14-9890-8cfff3bd3349",
"name": "Projects",
"items": [
{
"name": "FRCA1"
},
{
"name": "Bridge"
},
...
]
}

How to Retrieve Forms Data

Retrieving forms data is similar to retrieving reference-lists. You just need to specify the “userForm” as type.  Here are the steps:

  1. Authenticate and obtain the Access-Token (if you haven’t done so). Similar to what is described for Reference-Lists.
  2. Get Forms IDs
  3. Get the full form by ID

Get Forms IDs

Form data can be downloaded using its ID. The ID’s can be obtained by getting a list of forms and IDs first.

List of User Forms
URL https://api.xformsweb.com/contents/type/userForm?select=id,summary
Request Type GET
Header Authorization: Bearer <access-token>
Request Body
Response Body [
{
"id": "b5e9dbad-2f80-7e69-16c0-3a1297c29b93",
"summary": {
"formName": "Daily Jobsite Checklist",
"submitTime": 1531635093177,
"templateType": "DJS",
"userInit": "AD",
"userName": "Admin Demo"
}
}, ...
]

Comments This returns the ID and summary section of each form, which can be used to identify

the right form.

Get Form Data by ID

Using the Form ID, the form details can be retrieved, as below.

User Forms by ID
URL https://api.xformsweb.com/contents/b5e9dbad-2f80-7e69-16c0-3a1297c29b93
Request Type GET
Header Authorization: Bearer <access-token>
Request Body
Response Body {

"id": "b5e9dbcd-2f80-7e69-16c0-3a1297c29b93",
"name": "Daily Jobsite Checklist",
"templateId": "4b46436d-6fe5-4ff4-8ee4-152756e8559d",
"templateType": "DJS",
"summary": {
"formName": "Daily Jobsite Checklist",
"submitTime": 1531635093177,

"templateType": "DJS",
"userInit": "AD",
"userName": "Admin Demo"
},
"userId": "2eb21651-fe58-4d51-841a-e3337c4386a7",
"formData": [
{
"data": [
{
"name": "Project_Name",
"value": "Proj Test"
},
{
"name": "Project_Number"
  },
{
"name": "Project_Location"
},
{
"name": "Prepared_by Full Name",
"value": "Admin Demo"
},
  ...
}