Follow

GET Entries

The Form Entries API provides access to form entry data submitted by users for a specified Provider. 

Data retrieved can be filtered by Form code and date range.

Form Entry data is retrieved as “Raw” entry data - i.e. the raw answer values in hierarchical form.

We plan to release a more full featured Form Entries API in the future, which will include more detail such as the data type of each answer value.

On the Cloud this API is available via SSL secured HTTPS connection using the REST GET verb:

https://secure.formsonfire.com/api/v1/formentriesraw 

NOTE: This API implements pagination, and as such you must cater for this when you connect to our platform.

 

Answer Data Types

The various Form field types and their associated answer data formats are outlined below. 
Form Entry data is returned according to these data formats.

Question Type

Answer Data Format

Description

Text

String

Answers are provided in raw string format with no escaping

Number

String

Numbers are provided as strings, with decimal places intact when specified.  No formatting (e.g. currency, thousand separators) is applied.

Date & Time

String
YYYY-MM-DDTHH:MI:SSZ

Date and time as recorded by the user.  Time zone is UTC; time is in 24 hour values.
The “T” and “Z” in the format are delimiters.
This format is also known as extended ISO-8601.

Date Only

String
YYYY-MM-DD

Date as recorded by the mobile user.  The date has no time or time zone information

Time Only

String
HH:MI:SSZ

Time as recorded by the mobile user.  The time has no time zone information.

Choices

String

The value(s) of the option(s) selected by the user.  For multiple choice questions, the answers are packed into this single string, separated by a pipe character (“|”).

Location

String
lat long altitude accuracy

The geographic point as recorded by the user, based on the ISO 6709 format. Latitude and longitude values are in decimal degrees, altitude and accuracy are in metres.
Points that are chosen from a map are always reported as having 0 altitude and 5 accuracy.

Media and Drawings

String

The file name of the media file recorded by the user.  Generally images are in JPG format, audio is in WAV or 3GP, video in MP4 or MOV.

This file name must be used in a Media API call in order to retrieve the actual file contents.  See Media API below.

Barcode

String

The raw string value extracted from the barcode or QR code

Groups, Checklists, Geolists

Collection

Groups are included in Raw Form Entries as an enclosing collection which contains all questions within that group. 
For Flat Form Entries, groups are not included in the data output, since any repeats of data imply a repeatable group.

 

GET Parameters

The required and optional parameters for a GET call to the Raw Form Entries API are outlined below.

Parameter Name

Data Type

Required

Description

Format

String

Yes

Specifies the desired format of the response.
Must either JSON or XML.

ProviderId

Integer

Yes

Your unique Provider Id found on the Organization Setup page of the secure website (under My Account).

Integrationkey

String

Yes

Your unique Integration key found on the Organization Setup page of the secure website (under My Account).

FormCode

String

Yes

Code of the Form to fetch entries for

FormVersion

Integer

No

Version of the Form that you wish to fetch entries for.
To always get entries for the latest Published version, set this field to zero (0).
Defaults to 0 if not set.

FromDate

DateTime
(YYYY-MM-DDTHH:MI:SS)

Yes

Only return Form entries completed on or after the given Date and optional Time

ToDate

DateTime
(YYYY-MM-DDTHH:MI:SS)

No

Only return Form entries completed on or before the given Date and optional Time.
Defaults to 31 December 2049 if not set.

 PageNo  Integer  No The page number of the result set that you wish to receive back.
Defaults to 0, which is the first page of the result set.
 PageSize Integer   No The number of items returned per page.
Maximum value of 100.
Defaults to 100.

 

GET Response

The data returned from a Raw Form Entries GET is provided as a collection of form entries housed within nested property fields.

Form Entries Response (<FormEntriesRawResponse>)

Field Name

Data Type

Description

Entries

Collection of Raw Form Entry

Collection that contains all form entries found

ResponseStatus

ResponseStatus

Contains response errors if any occur – helpful for support and debugging purposes

 TotalRows  Integer The total number of rows found for the requested parameters.

Using the PageSize that you passed into your request, you can calculate how many pages of data are available.
i.e. PageSize / TotalRows = Total number of pages

Raw Form Entry (<FormEntryRaw>)

Field Name

Data Type

Description

Id

GUID

Unique identifier of the Form Entry

FormCode

String

Form code that this Entry relates to

FormVersion

Integer

Form version that this Entry relates to

UserExternalId

String

The external identifier assigned to this app user.  This is for linking users into other systems by a common ID.

UserFirstName

String

First name as registered for the app user

UserLastName

String

Last name as registered for the app user

UserEmail

String

Email address as registered for the app user

CompleteTime

DateTime
(YYYY-MM-DDTHH:MI:SS)

Date and time the form entry was completed by the user. Time zone is UTC; time is in 24 hour values.
The “T” in the format is a delimiter.

Latitude

Double
(Decimal Degrees)

Latitude of the user when completing the form entry.
This value will be null or 0 when GPS is turned off or fails to capture during form entry.

Longitude

Double
(Decimal Degrees)

Longitude of the user when completing the form entry.  This value will be null or 0 when GPS is turned off or fails to capture during form entry.

AnswersXml

XML

Raw form entry answers in hierarchical XML format, with a root element named “data”. 
Question data names are the XML element names, with answer values enclosed as strings.
This field is only populated when making a XML format request.

AnswersJSON

JSON

Raw form entry answers in JSON array format.
Question data names are the JSON property names, with answer values enclosed as strings.
This field is only populated when making a JSON format request.

 

API Usage Example

Given that the API is REST based, you can access the API directly via your web browser to test it. 
Obviously for actual integration works, you will need to make a web request to the given REST URL and then parse the response.

Below is a simple GET example which gets the answers for a specific day (23 July 2012), using XML response types.

GET Request

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<FormEntriesRawResponse>
   <ResponseStatus />
   <TotalRows>675</TotalRows>
   <Entries>
      <FormEntryRaw>
         <AnswersJson />
         <AnswersXml>
            <data>
               <name>John Smith</name>
               <experiencechoice>SECT</experiencechoice>
               <selectmulti>PB|TT|DX</selectmulti>
               <MapsGeoPoint>-26.2858679873348 128.688879013062 0 5</MapsGeoPoint>
               <audio>1029939382883.wav</audio>
               <photosgroup>
                  <photo>102944442883.jpg</photo>
                  <photo>102955553828.jpg</photo>
                  <photo>443493938286.jpg</photo>
               </photosgroup>
               <signagegroup>
                  <stop>1</stop>
                  <caution>1</caution>
                  <barrier>1</barrier>
                  <detour>1</detour>
               </signagegroup>
               <integer>2</integer>
               <datetime>2012-07-23T10:59:30Z</datetime>
               <dateonly>2012-07-23</dateonly>
               <timeonly>20:59:36Z</timeonly>
            </data>
         </AnswersXml>
         <CompleteTime>2012-07-23T10:59:47</CompleteTime>
         <FormCode>DEMO-001</FormCode>
         <FormVersion>3</FormVersion>
         <Id>e2098623-4753-4c0b-816c-5b4efaa64be4</Id>
         <Latitude>-26.2844297653253</Latitude>
         <Longitude>128.684420511265</Longitude>
         <UserFirstName>John</UserFirstName>
         <UserExternalId />
         <UserLastName>Smith</UserLastName>
      </FormEntryRaw>
   </Entries>
</FormEntriesRawResponse>
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk