API’s & Integrations

XForms uses RESTful APIs to communicate between its mobile apps, reporting/admin web app, and it’s form template designer toolset.  This same set of APIs can also be used by other software tools to leverage the power of XForms’ field data capture into other systems.

Generalized Use Case

With the XForms APIs, you could use XForms for field data capture, and then extract that data out of the XForms database for insertion into your existing enterprise reporting dashboard software. 

Basic Actions

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"
},
  ...
}

You can also use most 3rd party integration tools such as Zapier, Make.com, Integrately, etc to connect XForms to other software.  Some example integrations are listed below.

Google Sheets

How to integrate table row data from a mobile form into Google Sheets

AirTable

Using XForms + Airtable to build a low-cost EHS and safety incident investigations management system

OneDrive

Upload your field forms and photos to OneDrive, automatically

MS Access

Mobile forms for egg pallets transportation?

Integration with on-prem Backend MS Access dB