General Information on the API

 

API Usage Limits

API calls to the ProntoForms are limited to 2500 a day per team. The limit is shared across all applications within the team. 

API calls are also limited to a maximum of 3 simultaneous requests per API key.  Customers are limited to 3 API keys.   

Please contact support@prontoforms.com if these limits pose a problem for your application. 

[ top ]

 

API Domain

All API URLs should be accessed via the domain api.prontoforms.com.

[ top ]
 

 

Authentication Method and HTTPS Protocol Support

The API currently uses basic authentication. This was chosen for the simplicity and pervasiveness that Basic provides. API requests are required to transmit over SSL (HTTPS) to ensure your credentials are safe and secure.  The HTTP protocol is not supported.
[ top ] 

 

Setup an API Application in ProntoForms

Before you can connect your application to the API, you must first setup an API application.  This will provide the credentials you need in order to connect.
[ top ] 

 

Versioning

API URLs contain a version number. This will allow us to upgrade our API in the future while still continuing to support existing API clients. Replace [version] in this document with the version you are developing against. We are currently at version 1.
[ top ]

 

Help with Extended Request Types (PUT and DELETE)

We use the full set of request methods in our API (GET, POST, PUT, DELETE). If you find your client library does not support the extended types, you have the option of reverting to POST and adding the request parameter "_method", setting the value to the desired request method. For example:
POST "/users/13123?_method=DELETE"
will delete the user with ID 13123.
[ top ]

 

Using POST and PUT Requests to Create and Update

 The POST (for create) and PUT (for update) request methods are used in the API.  These method types require the inclusion of a request body in XML or JSON format.  Sample request bodies, usually in both XML and JSON format, are provided for each method described in this documentation.  Please note that the request body should not be URL encoded before being sent to the ProntoForms API.

[ top ]
 

Supported Media Types

The API supports XML or JSON message payloads for most provisioning requests, and as the format of data returned from API method calls. The media type is specified by appending ".xml" or ".json" to your request. The Accept and Content-Type request headers are ignored.

For example:

  • XML – https://api.prontoforms.com/api/1/users.xml
    Request to return an XML-formatted list of users 
  • JSON – https://api.prontoforms.com/api/1/users.json
    Request to return an JSON-formatted list of users  


IMPORTANT:  Strict encoding of JSON is enforced.  All keys must be placed in quotes.

Please ensure that any special characters sent to the ProntoForms API are properly escaped.  For further information, please consult the following URLs:
http://en.wikipedia.org/wiki/XML#Characters_and_escaping
http://www.json.org/

[ top ]

 

Date and Time Formats

All date and time formats follow ISO formats, and should be sent in UTC.

Timestamp:  yyyy-MM-dd'T'HH:mm:ss'Z'
Date:  yyyy-MM-dd
Time:

 HH:mm:ss'Z'

 [ top ]

 

UTF-8 Encoding

Every string passed to and from the API should be UTF-8 encoded. To avoid any errors or errant characters, please ensure your programs and libraries support UTF-8 and be sure any Unicode strings you take as input from a user are converted before sending the data to ProntoForms.

 [ top ]

 

ProntoForms REST API Code Samples

Please refer to specific sections of the API for usage samples.  Many of the REST API functions can be executed by simplying loading a URL over HTTPS.  Where XML or JSON messages are required for an API function, sample messages have been provided.  Additionally, samples of the XML or JSON response body messages from the server can be found in each section.  In most cases, REST API samples using the CURL command line utility are provided (see below for more information on CURL). 

There are a number of excellent tutorials and code sample libraries for using REST APIs freely available on the web.  The ProntoForms API is a typical implementation of REST, so much of this content is directly relevant.  One of the best free resources, which includes code samples in 7 programming languages, is the following:
Learn REST:  A Tutorial

The following sites also provide excellent information on REST APIs:
Learn REST:  A RESTful Tutorial
A Beginner's Guide to HTTP and REST

[ top ]

 

Using CURL or Alternatives to Test and Debug Your API Clients

When getting started with the ProntoForms REST API, we recommend using a simple command-line tool like CURL to debug and test your work. In the REST API documentation We have provided examples of curl commands that you can customize and try out for yourself.

Please note that CURL and its pre-requisites are 3rd party software. It is freely available for a very wide range of operating system platforms. Please visit the CURL website to download a version for your system. Unfortunately, the ProntoForms support team cannot provide assistance with any problems you may have with the installation or operation of CURL on your computer. Before attempting to install CURL, as with any other software, it is recommended that you check the download with an up-to-date virus scanner and ensure that you have a recent backup of your system. Please also note the important points below.

SSL support is required
The security reasons, the ProntoForms REST API is available only through https connections. Depending on your platform, this may require the installation of a software package like OpenSSL. For Windows computers, we have successfully used distributions from this site. Again, this software is not supported by ProntoForms Support, and you should backup your system before installing.

CURL for Windows Library Issues
Some Windows users who are new to CURL experience various dll-related errors when they first try to use it. Often, these dll errors can be resolved by installing the Microsoft Visual C++ Redistributable Package. There are various versions of this package available, depending on your hardware or OS version. Please consult the Microsoft support site, or try a Google search for the package. It is highly recommended that you perform a backup of your system before installing such a package.

[ top ]

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

Comments

  • Avatar
    stephen Grant

    Does the API only provide access to "backend" processes, or can we use it to add extensions to the "frontend" (the client app)? In particular, I have a potential application wherein we want to gather user-specified data from a bluetooth or NFC connection. That is, the end user has some custom gear that generates data; we want to capture that data through a BT or NFC call. (similar to what prontoforms can do if I've sourced my GPS information from an external GPSr rather than the internal Blackberry GPS.

     

    We can program the external device to send BT or NFC in a defined format to the smartphone; can we also program the Prontoforms client to look for that external device and accept the data in a defined format?

  • Avatar
    GlennMC

    The ProntoForms API only provides access to "backend" or server processes, as you describe. We don't have an API for the mobile apps.

     

  • Avatar
    Swami Chandrasekaran

    I see in the API's there is a concept of a User entity. Say I were to use Prontoforms in a public cloud situation, and if the customer type happens to be an enterprise / SMB.

    • Where and how do I specify the enterprise name and associated details?
    • I see in the createUser API, there is an optional <groupIds> element. How do I create a group? I don't see a published API
  • Avatar
    Mengxi Liao

    Dose the api allows users programmatically modify the forms. We have several forms that use multiselect box that share one email list and the list may change very often. But multiselect does not support datasource. Is there any way using api the get around this (or other suggestions)?

  • Avatar
    GlennMC

    Hi Mengxi,

    We will be adding support for the use of data sources with multi-select questions in an upcoming release.  We don't have an exact date yet, but we expect it will be available in the next 2 or 3 months.

    /Glenn

     

     

  • Avatar
    Joseph Holt

    Will ProntoForms multi-select questions allow individual API push per answer for each dropped down selector?