API: Data Record Retrieval and Deletion

The following API operations are available for the purposes of data record retrieval:

 

Retrieve a List of Data Records

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

URL Structure

api.prontoforms.com/api/[version]/data.xml
api.prontoforms.com/api/[version]/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 Data Records belong to
 fids  no    Comma-separated set of Form Identifiers the Data Records belong to
 gids  no    Comma-separated set of Group Identifiers the Data Records must have been submitted by
 uids  no    Comma-separated set of user Identifiers the Data Records must have been submitted by
 unames  no    Comma-separated set of Usernames the Data Records must have been submitted by
dataState     State of form processing.
executionState     Success/Failure of data record processing.
state     Progress of data record 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 Data Record
 DataRecordProcessedDate  Date the Data Record was processed and all destinations completed
 DataRecordCompletedDate  Date the Data Record was uploaded to server from device 
 DataRecordLastUpdatedDate  Date the Data Record was last updated. Changes as the Data Record  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/data.xml
curl -v -k -u user:password -X GET https://api.prontoforms.com/api/1/data.json

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

[ top ]

 

Retrieve a full Data Record

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

Data records 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 data record XML format is documented in the following article:
Data Record XML Formats: Standard vs. Labels as Node Names

URL Structure

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

api.prontoforms.com/api/1/data/[id]/documents/[document_id]

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

The final structure downloads the data record document in whatever format has been set for that document - i.e., 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

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

How to Find ID Values Using the Web Portal

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 Data Record.

Sample cURL Commands

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

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

[ top ]

 

Retrieve the attachments of a Data Record

Use this methods to retrieve the attachments of a Data Record.   The attachments are provided in a ZIP file.

URL Structure

api.prontoforms.com/api/[version]/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 Data Record. 

Sample cURL Command

curl -v -k -u user:password -X GET https://api.prontoforms.com/api/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 data record ID.

[ top ]

 

Retrieve an attachment of a Data Record

Use this methods to retrieve a single attachment of a Data Record.  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/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 data record ID, and replace [attachment_id] with an attachment ID.

[ top ]

 

Delete a Data Record

Use the following information to permanently delete a Data Record via the API.

URL Structure

api.prontoforms.com/api/[version]/data/[id].xml
api.prontoforms.com/api/[version]/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/data/[id].xml
curl -v -k -u user:password -X DELETE https://api.prontoforms.com/api/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 data record 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