API: Updating a Data Source (Lookup)

 

Before You Begin

Note that the API only supports updating a Data Source data, not creating or renaming a Data Source.  You must create your Data Source through the web administration before setting up an API Data Source update script.

 

Upload a New Data Source Table

This method updates the data table of a Data Source.

URL Structure

All URLs below are accessible via HTTPS only (HTTP not allowed).  In the samples below, "[fs_id]" and "[ds_id]" represent the form space and data source IDs (visible in the portal). 

api.prontoforms.com/api/[version]/formspaces/[fs_id]/sources/[ds_id]/upload.csv
api.prontoforms.com/api/[version]/formspaces/[fs_id]/sources/[ds_id]/upload/user/[id].csv
api.prontoforms.com/api/[version]/formspaces/[fs_id]/sources/[ds_id]/upload/user/username/[username].csv
api.prontoforms.com/api/[version]/formspaces/[fs_id]/sources/[ds_id]/upload/group/[id].csv

 

Note: URLs pointing to a specific user or group are used to update data source overrides.  Overrides are deprecated and have been replaced by data partitioning.  Existing overrides can still be updated. In most cases, however, it is recommended that organizations transition to either using partitions to filter their data sources, or to configure filtered lookups in the Form Builder.  

[ top ]

 

Document Data Types

CSV, JSON, XML

Method

PUT

[ top ]

 

Request Parameters

 Parameter  Required  Default value  Description
 delimiter  no  ,   For CSV documents, the CSV delimiter.
 encoding  no  utf-8  Specifies the character encoding of the CSV content.  For CSV content generated from Microsoft Windows environments, set this parameter to "windows-1252". 
 suppressPush   no  false  Specifies if the data source update action should trigger any configured push notifications to mobile users 

[ top ]

 

Request Body Samples

CSV

 

Response Body Samples

None

[ top ]

 

Sample cURL Commands

curl -v -k -u user:password -X PUT --upload-file FILENAME.csv https://api.prontoforms.com/api/1/formspaces/[fs_id]/sources/[ds_id]/upload.csv
curl -v -k -u user:password -X PUT --upload-file FILENAME.csv https://api.prontoforms.com/api/1/formspaces/[fs_id]/sources/[ds_id]/upload/user/[id].csv
curl -v -k -u user:password -X PUT --upload-file FILENAME.csv https://api.prontoforms.com/api/1/formspaces/[fs_id]/sources/[ds_id]/upload/user/username/[username].csv
curl -v -k -u user:password -X PUT --upload-file FILENAME.csv https://api.prontoforms.com/api/1/formspaces/[fs_id]/sources/[ds_id]/upload/group/[id].csv

 

Important Notes:

  • Replace user with your API Key ID and password with your API Key secret.
  • Replace FILENAME with the name of your actual file which should be formatted as per the CSV request body samples above.
  • Replace [fs_id] with your formspace ID.
  • Replace [ds_id] with your data source ID.
  • Replace [id] with whichever ID should belong according to whatever precedes it.  For example, in the second cURL command you would replace [id] with a specific user ID.  In the last command, [id] would be replaced with a group ID.

[ top ]

 

Error Codes

Error Code
Response Header
HTTP Response
Code
Description
 SourceHeaderTooLong 400  One of the column headers in your data file is too long.  Headers can be at most 255 characters.

[ top ]

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

Comments

  • Avatar
    Bradley V.

    Does this not return anything, not even headers, when things go as planned?

  • Avatar
    GlennMC

    Hello Bradley,

    When things go as planned with this API call, there will be an HTTP response with at least 2 headers.  One of these will be the HTTP response code of "200".  

    If an error occurs, you will get a non-200 response code header along with more headers with problem information, as documented here:

    https://support.prontoforms.com/entries/21017302-Error-Handling

    /Glenn

     

     

  • Avatar
    Sunil Pai

    Is there a way to trigger a data source that is not a CSV upload to fetch its details again? For example, one tied to a Google Spreadsheet?

  • Avatar
    Danielle Morley

    Hello Sunil,

     

    The API can only update a Manual Upload data source.  For other data sources like Google Spreadsheet, we recommend setting up a fetch schedule at regular intervals (such as hourly) to cover this need.

     

  • Avatar
    Sunil Pai

    Thanks, Danielle. Since you have the ability to "Fetch New Data" for a data source through the web UI, I had assumed it could be done through the API. I would encourage adding this as a feature in the future.

  • Avatar
    Sunil Pai

    Currently Data Sources have a checkbox to "Push updates to devices after a fetch". Does this push only when the datasource has been changed, or on every fetch regardless of changes? The reason I ask is that we recently activated push notifications, but now our users are reporting that they are being told to update their ProntoForms every hour even though I'm confident that none of our data sources are changing that frequently.