API: Form Submission Retrieval and Deletion

The following API operations are available for the purposes of form submission retrieval:

 

Retrieve a List of Form Submissions

Use this method to retrieve a list of your Form Submissions.  Optionally, you may include a filter to narrow the results.  Calling this method will return a paged list of Form Submission headers.  If the number of items exceeds the size of the page, subsequent requests can be made in order to retrieve the full list.

NoteFor details about how long we store form submission data, see the topic Form Submission Retention and Deletion.

URL Structure

api.prontoforms.com/api/1.1/data.xml
api.prontoforms.com/api/1.1/data.json 

Method

GET

Request Parameters

 Parameter  Required  Default value  Description
 p  no  0 0-based page number.
 s  no  100 Number of results in the page.  The maximum value is 100.
 tz  no  UTC Time zone to present all dates in.
 stime  no   Lower-bound limit on the Date set with the ftime parameter
 etime  no   Upper-bound limit on the Date set with the ftime parameter
 ftime  no  DataRecordProcessedDate*  Date/time format
 fsids  no   Comma-separated set of FormSpace Identifiers the Form Submissions belong to
 fids  no   Comma-separated set of Form Identifiers associated with the Form Submissions
 gids  no   Comma-separated set of Group Identifiers the forms must have been submitted by
 uids  no   Comma-separated set of user Identifiers the forms must have been submitted by
 unames  no   Comma-separated set of Usernames the forms must have been submitted by
dataState     State of form processing.
executionState     Success/Failure of Form Submission processing.
state     Progress of Form Submission processing. 

Read more about dataState, executionState, and state. 

 

*Note: The following options exist for the ftime Value parameter:

 Option  Description
 DeviceEntryDate  Date the user hit 'submit' according to the device  
 ServerReceiveDate  Date the server initially received the Form Submission
 DataRecordProcessedDate Date the Form Submission was processed and all destinations completed
 DataRecordCompletedDate Date the Form Submission was uploaded to server from device 
 DataRecordLastUpdatedDate Date the Form Submission was last updated. Changes as the submission goes through dispatch, processing, etc.

 

Sample Responses

XML

<pagedList totalNumberOfResults="1">
  <dataRecord identifier="123">
    <referenceNumber>20150619-1823904173</referenceNumber>
    <state>Complete</state>
    <dataPersisted>true</dataPersisted>
    <serverReceiveDate>2015-06-19T17:07:35Z</serverReceiveDate>
    <formVersionId>152479483</formVersionId>
    <formId>141737557</formId>
    <userId>131413101</userId>
    <username>testing1</username>
  </dataRecord>
</pagedList>

JSON

{
  "totalNumberOfResults": 1,
"totalNumberOfPages":1,
"zone":null,
  "pageData": [
{
    "identifier": "1823904173",
    "referenceNumber": "20150619-1823904173",
    "state": "Complete",
    "actionState": "Complete",
    "dataPersisted": true,
    "serverReceiveDate": "2015-06-19T17:07:35Z",
    "formVersionId": "152479483",
    "formId": "141737557",
    "userId": "131413101",
    "username": "testing1"
  }
]
}

Sample cURL Commands

curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data.xml
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data.json

Important Note: Replace user with your API Key ID and password with your API Key secret.

[ top ]

 

Retrieve a full Form Submission (or Form Submission Document)

Use these methods to retrieve a full Form Submission. You can retrieve a Form Submission in any document format linked to the form. You can also retrieve a Form Submission in either JSON or XML format; referring to a document is optional. 

Form Submissions in XML format include a reference to an XML schema document (XSD), which describes the ProntoForms XML format.  The current XSD is available at the following URL:
https://live.prontoforms.com/resources/schema/data/v1.xsd

The standard Form Submissions XML format is documented in the following article:
Form Submission Formats: Standard vs. Labels as Node Names

URL Structure

api.prontoforms.com/api/1.1/data/[id]/document.xml
api.prontoforms.com/api/1.1/data/[id]/document.json
api.prontoforms.com/api/1.1/data/[id]/documents/[documentId]

The first two will download a full submission in standard XML or JSON format, based on the extension you choose.

The final structure downloads the Form Submission document in whatever format has been set for that document -that is, it cannot be modified using different extensions on the URL structure.  For the full range of supported document types and customization options, please consult the following documentation:
Documents & Data Formats (V1)

Overview: V2 Documents

Documentation on how to find the Document Template ID is available in the following article:

How to Find ID Values Using the Web Portal


Changes to the Form Submission Format:
For ProntoForms REST APIs and JSON/XML document formats, we maintain a practice of not deleting existing properties or objects. A mechanism for versioning is used to facilitate deletions to our JSON/XML formats when necessary.  Customers will be contacted in advance if they will be affected. 
However, we will occasionally add new properties to existing APIs to support new features in the ProntoForms Platform. We do not create a new version of our APIs for new properties and we advise that clients of our APIs are resilient to additions by ignoring unknown properties. Client applications should ignore any properties that are not relevant to their use case.

 

Method

GET

Request Parameters

 Parameter  Required  Default value  Description
 tz  no  UTC Timezone used to present timestamps.
 a  no  true Boolean indicating if attachments should be embedded in the document.

 

Request Body Samples

This method does not make use of a request body.

Response Body Samples

The response body contains the bytes of the Form Submission.

Sample cURL Commands

curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data/[id]/document.json
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data/[id]/document.xml

Important Note: Replace user with your API Key ID and password with your API Key secret. Also, replace [id] with a form submission ID.

[ top ]

 

Retrieve the attachments of a Form Submission

Use this method to retrieve the attachments of a Form Submission.   The attachments are provided in a ZIP file.

URL Structure

api.prontoforms.com/api/1.1/data/[id]/attachments.zip

Method

GET

Request Parameters

None.

Request Body Samples

This method does not make use of a request body.

Response Body Samples

The response body contains the bytes of the ZIP file containing the attachments of the Form Submission. 

Sample cURL Command

curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data/[id]/attachments.zip

Important Note: Replace user with your API Key ID and password with your API Key secret. Also, replace [id] with a form submission ID.

[ top ]

 

Retrieve an attachment of a Form Submission

Use this method to retrieve a single attachment of a Form Submission.  Do not append a file extension to the attachment_id in this method call, as it will have no effect on the file format of the response.  The server will respond with the type of file originally submitted with the form.  To determine the type of file, examine the "Content-Type" header of the response to this call.

URL Structure

api.prontoforms.com/api/[version]/data/[dataRecord_id]/attachments/[attachment_id]

Method

GET

Request Parameters

None.

Request Body Samples

This method does not make use of a request body.

Response Body Samples

The response body contains the bytes of the attachment you requested.

Sample cURL Commands

curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1.1/data/[id]/attachments/[attachment_id]

Important Note: Replace user with your API Key ID and password with your API Key secret. Also, replace [id] with a form submission ID, and replace [attachment_id] with an attachment ID.

[ top ]

 

 

Delete a Form Submission

Use the following information to permanently delete a Form Submission.

NoteThe data is deleted immediately from ProntoForms' servers and 45 days later from the Disaster Recovery storage.

URL Structure

api.prontoforms.com/api/1.1/data/[id].xml
api.prontoforms.com/api/1.1/data/[id].json 

Method

DELETE

Request Parameters

None.

Request Body Samples

This method does not make use of a request body.

Response Body Samples

This method does not send a response body.

Sample cURL Commands

curl -v -k -u user:password -X DELETE https://api.prontoforms.com/api/1.1/data/[id].xml
curl -v -k -u user:password -X DELETE https://api.prontoforms.com/api/1.1/data/[id].json

Important Note: Replace user with your API Key ID and password with your API Key secret.  Also, replace [id] with a form submission ID.

Error Codes

There are no method-specific errors for this method.
Consult the API Error Handling reference for general information on error handling.

[ top ]

Was this article helpful?
3 out of 3 found this helpful
Have more questions? Submit a request

Comments

  • Avatar
    Judah Sali

    Is there an api for requesting a list of Forms? 

  • Avatar
    GlennMC

    Hello Judah,

    Unfortunately, the API does not currently support returning a list of forms.

    /Glenn

  • Avatar
    Sterling Swartwout

    What are the valid values for document_id? Didn't see any reference in my List of Data Records.

  • Avatar
    Mike Stonitsch

    Yes this won't work

    What is document id?  It should end with [document_id].json   Where do we get document id?

     curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1/data/[id]/documents/[document_id]

  • Avatar
    Jacinta Sarpkaya

    Hi Mike,

    The document ID is the unique identification number of the document your form once it has been filled out and submitted. This essentially controls the ways you can view your data. 

    To find your document ID, 

    • In the web portal, mouse over the Manage Forms dropdown in the main navigation panel, and select* **Documents.*
    • Click on the name of the JSON document being used.
    • On the following page, look at the address bar of your web browser.  The document ID appears after "documents" in the URL. I've highlighted it in red in the image below.

    Doc_ID.png

     

    Is that helpful?

  • Avatar
    Mike Stonitsch

    Thanks Jacinta,

    I can receive header data fine.

    My problem now is to retrieve "Detail" data I must have destination for my document setup?

    For example I have a JSON document created and tied it to the form and I have not created a "Destination".  When I make the API get call, it says:

    Your API call resulted in an error.  Please see the HTTP Headers for details.  Error message: Form Document Link Does Not Exist: Document 'JSON - Example' is not an additional document of Form 'Survey' (ID 9999999-9999-8888-aaaa-a4484884ssks)

    Thanks,

    Mike

  • Avatar
    Jacinta Sarpkaya

    Hi Mike,

    Do you know if you have your JSON document as an "additional document available for download"?  Documents labeled as such are made available for download through the API, so turning on this setting may fix your issue. There is documentation on that here:  https://truecontext.zendesk.com/entries/94006786-The-Destinations-Tab#Additional.

    If you have that set up and it still isn't working, please let me know so I can create a support ticket for you. Our support team will be able to take a closer look.

    Thanks,

    Jacinta