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>