Remote Data Retrieval
The data collected using the Form.com platform can be retrieved (exported), and in most cases, without having an active session of an account or without having to log in at all.
You can then integrate your data into certain external applications or services using a custom generated URL.
The Remote Data Retrieval feature can be used in the reports with the Public status only.
Export to XML
Due to the security measures, you must be logged into the account (in a live session) to export your data as XML.
The structure of a data retrieval URL depends on what is being exported.
URL structure for exporting forms
Form.com account: https://app.form.com/servlet/ExportSurveyToXML/export?importSurveyStructure=1&plain=1&selectedSurveys=XXXXXX&snapshotId=abc
URL structure for exporting form results, data models, contact managers
Standard report
Form.com account:
Custom report
Form.com account:
Alternatively, if you want to export to XML using API, be sure to use cookies from a live login session.
Use the structure shown below when exporting data models or contact managers:
Form.com account: https://app.form.com/servlet/ExportSurveyToXML/export?importResponses=1&completesOnly=true&plain=1&selectedSurveys=XXXXXXXX&dm=true
When exporting data models or contact managers the dm=true parameter must be added to the URL structure (no need to use the dm=false parameter otherwise).
XXXXXXXX corresponds to the ID of a contact manager or data model exported. The IDs can be obtained from the URL when editing the сontact managers or the data models in the admin area of the platform.
Parameters used in URLs
importSurveyStructure=1 — if this parameter is used, then the form structure will be exported.
importResponses=1 — if this parameter is used, then the form results (responses) will be exported.
plain — this parameter indicates if the data is being exported as text or a ZIP archive.
plain=1 — text
plain=0 — ZIP
completesOnly — can be used if exporting form/survey results.
completesOnly=true — only completed responses will be exported.
completesOnly=false — both completed and partially completed (in progress) responses will be exported.
selectedSurveys — obligatory parameter that contains survey/form ID that can be retrieved from the form's Master URL.
selectedReports — this parameter is used to specify a type of exported report.
selectedReports=1 — exports a standard report.
selectedReports=XXXXXX — exports a custom report with the <XXXXXX> report ID. You are able to export multiple reports for the same form by specifying multiple Report IDs using the structure: selectedReports=(XXXXXXX,XXXXXXX).
snapshotId — this parameter is used for caching of exported results. You can use any set of random symbols, for example: abc, 12345, qwert, q1kkwke or any other. New data is exported for each unique parameter used. If the parameter had already been used, the data exported with that unique parameter will be exported once again.
dateFrom, dateTo, dateFormat — you can use these parameters to filter responses by submission dates:
If dateFormat is not specified, the default format is: yyyy-MM-dd.
If dateFrom is not specified, the retrieved results will include all responses submitted before the dateTo value.
If dateTo is not specified, the retrieved results will include all responses submitted after the dateFrom value.
If you must specify the submission date up to minutes and seconds, then the dateFormat parameter should appear as: dateFormat=yyyy-MM-dd HH:mm:ss.
dateModified — use this parameter in addition to the dateFrom, dateTo, dateFormat parameters to filter responses by the dates they were modified:
dateModified=by_respondent (or if the parameter is omitted entirely): dateFrom, dateTo, dateFormat parameters filter data by the submission date of the form.
dateModified=by_admin: filters responses by the date they were modified by the form admin.
dateModified=by_any: filters responses by the date they were modified by anyone (either the form admin or the respondents).
The parameter only works if it is used with the following tags in the link: dateFrom, dateTo and ver=latest.
rbrLink — use this parameter to export a link to individual report by respondents.
rbrLink=true — exports the link to a report by respondents. The link will be located under the Submit date time parameter in the exported XML file. An option to download the responses as PDF will also be available and the link for it will be inserted within the RbrPdfLink description element in the exported XML file.
ignoreHtmlTags — use this parameter if you have customized your form's questions and answer options text using HTML and you would like to specify whether to include this information in your custom report.
ignoreHtmlTags=true — exports answer choices labels with the HTML tags included.
ignoreHtmlTags=false — ignores HTML and exports plain text only.
includeUniqueUrl — use this parameter to include the unique link to a particular form or survey, which will appear as the surveyUniqueUrl in the final link.
Export versioning
You can specify whether to use the latest changes made to the XML exporting structure or keep your current structure. For this the ver parameter should be added to the export URL, where:
ver=1 — uses the current version of the XML export structure (the absence of the parameter or its value will be treated like ver=1).
ver=2 — uses the changed version of the XML export structure.
ver=latest — uses the latest version of the XML export structure.
If no parameters are specified, retrieved results will include all submitted responses.
Export to Excel, CSV, SPSS
When exporting to Excel, CSV or SPSS, the URL should have the following structure:
Form.com account: https://app.form.com/servlet/ExportResults?SurveyID=XXXXXX&ReportID=-1&pw=xxxxxxxx&exportTo=3&labelsValues=1
Parameters used in URLs
SurveyID — a mandatory parameter and contains the survey/form ID which can be retrieved from the survey/form Master URL.
ReportID — a mandatory parameter that contains the report ID. Standard report’s ID is “1”. Custom report ID is six digits that follow survey/form ID in the report’s URL.
Pw — a mandatory parameter that contains 32 digits following the report ID in the report’s URL
exportTo — this parameter indicates the type of exported data.
exportTo=1 — Excel
exportTo=2 — SPSS
exportTo=3 — CSV
compatibleFormat — this parameter is only applicable when exporting to CSV.
compatibleFormat=1 — exports data in a format compatible with the Upload responses feature.
labelsValues — this parameter indicates whether results will be exported as labels, values, or both.
labelsValues=1 — labels only
labelsValues=2 — values only
labelsValues=3 — both labels and values
includeExcelSummary — applicable when exporting to Excel and indicates if the summary report will be exported in addition to the row data. Adding this parameter will include the summary report.
Include the parameter name in the URL to trigger the inclusion of its respective data in the export.Encoding — applicable when exporting to SPSS. This parameter defines characters encoding, e.g. UTF-8, KOI8-R.
includeUrlToRBR — use this parameter to include the link to download the individual report by respondent into your CSV report. Include the parameter name in the URL to trigger the inclusion of its respective data in the export.
access_token — this parameter includes the token you receive in the returned response after you make a request (see the 'Remote Data Retrieval Authentication' section below). The token can be found in the returned response to the API call, or an OAUTH token found in cookies from the live session.
For the Remote Data Retrieval of Excel and CSV files, additional variables can be inserted into the URL to customize headers and report data exported. Use 'true' or 'false' values to set these parameters:
include_references=true/false — specify whether to include or not include the Question references in the header.
include_qid=true/false — specify whether to include or not the Question Identifiers.
include_aid=true/false — specify whether to include or not the Answer Identifiers.
include_qtext=true/false — specify whether to include or not the question texts.
include_atext=true/false — specify whether to include or not the answers' texts.
include_qcodes=true/false — specify whether to include or not Question Analysis Codes.
include_rmeta=true/false — specify whether to include or not the Report Metadata
include_rid=false|true — specify whether to include a respondent's system ID into the exported file.
Remote Data Retrieval Authentication
If you have a custom domain name set up, you should use it instead of the app.form.com when creating links for the remote data retrieval.
To authenticate the Data retrieved using an access token:
getAuthenticationToken that gets a token which is valid within one hour and can be used once for login to the Form.com application. This service is applicable for all user types (user, account admin, admin).
Use the following request to get the token:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:aut="http://authentication.v81.api.keysurvey.com">
<soapenv:Header/>
<soapenv:Body>
<aut:getAuthenticationToken>
<!--Optional:-->
<login>APPLICATION_LOGIN_HERE</login>
<password>APPLICATION_PASSWORD_HERE</password>
</aut:getAuthenticationToken>
</soapenv:Body>
</soapenv:Envelope>You will receive the token in the response:
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:getAuthenticationTokenResponse xmlns:ns2="http://authentication.v81.api.keysurvey.com" xmlns:ns3="http://v81.api.keysurvey.com">
<return>55**1731**5118**51</return>
</ns2:getAuthenticationTokenResponse>
</S:Body>
</S:Envelope>2. Copy the returned token from the response.
3. Make an HTTP GET Request to retrieve the data using the structure specified above. For example:
If you have a custom domain name set up, you should use it instead of the app.form.com when creating links for the remote data retrieval.