The Form Entries API provides access to form entry data submitted by users.   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:

Raw Form Entries:
http://secure.formsfly.com/api/v1/formentriesraw

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 Organisation Setup page of the secure website (under Your Account).
Integrationkey String Yes Your unique Integration key found on the Organisation Setup page of the secure website (under Your Account).
FormCode String Yes Code of the Form to fetch entries for.   This is the External ID field shown on the form settings.
FormVersion Integer Yes 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).
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)
Yes Only return Form entries completed on or before the given Date and optional Time

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

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 both the JSON and XML response types.

GET Request

http://secure.formsfly.com/api/v1/formentriesraw?formcode=ROAD-001&formversion=36&fromdate=2012-07-23&todate=2012-07-23&integrationkey=xxxxxxxxxxxx&providerid=1&format=xml

XML Response

<FormEntriesRawResponse>
  <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></UserExternalId>
      <UserLastName>Smith</UserLastName>
    </FormEntryRaw>
  </Entries>
  <ResponseStatus />
</FormEntriesRawResponse>
REST Connector. API – GET Data Source. API – PUT Data Source. API – POST Form Entry to External Web Service. API – Form GET Entries. API – GET Users. API – PUT User. API – DELETE User. Advanced Integration. Integration API Overview. API – GET Tasks. Will it connect to our existing systems?. API FormsFly System. API – DELETE Task. API – POST User. API – POST Task. API – Form GET Media File.