We noticed that JavaScript is disabled in your browser. We suggest enabling it for a better experience.
We noticed you're using an older version of Internet Explorer. We suggest you update to the latest version for a better experience.
Skip to main content
Print

Use the OpenForms API

Only Admins can access the API screen in OpenForms. If you’re not an Admin, you can still use the API itself.

OpenForms has phased out support for version 1, 2, and 3 API keys.

As of July 2024, we no longer offer integrations built with these keys. 

If you're building a new integration today, make sure you're using a version 4 or later API key. If your organization uses integrations built on older version API keys, they will no longer work and you will need to create a version 4 key and update your integration. 

Not sure how to update? Contact support and we'll point you in the right direction. The OpenForms API lets you send requests to OpenForms and get responses about your OpenForms data. You can also use it to integrate OpenForms with another application, so requests can be sent between them.

Here are a few things you can do with it:

  • Get a list of responses to a form

  • Download a response as a PDF

  • Delete responses

  • Get a list of your organization’s published forms

  • Update the elements of a list

Access the API

All OpenForms data is hosted on our United States and Australian servers. Therefore, to receive your particular data, you'll need to authenticate your requests with an API Key linked to your OpenForms organization.

Generate a Key

  1. Go to Integrations >  Web API.

  2. Select Create API Key.

  3. Enter a Key name.

  4. Use the drop-down menu to select the API version.

  5. Check each box under Access to grant the permission.

    2019-07-30_14-23-35.png
    Permissions let you choose which services the API key can use. These are useful for allowing staff and external developers access to only what they need. 

  6. Select Create.

Manage API Keys

As you create API keys, they'll be listed in the Web API screen. You can select any of your API keys to change the permissions associated with it or select Edit from the ... menu.

You can also disable or delete individual keys at any time by selecting Disable key or Delete key from the ... menu. This can be useful when you've fully migrated to a newer version of the API, or developers with access to an API Key change roles in your organization. 

API Versions

The OpenForms API is regularly updated with new features and, sometimes, changes to the structure of requests. If you've written applications that are reliant on a previous version of the OpenForms API, make sure to use a key and documentation appropriate to that version. 

To see a full list of version features and request structures, select the API documentation in the OpenForms API screen, and choose your version in the API Explorer screen.

Use the API

To use the OpenForms API, you'll have to determine the request (or call) you'd like to make to the API, then implement that call into your application code.

Our API documentation details all of the available calls you can make to the OpenForms API, as well as the filters (or parameters) available for those calls.

Find and Test OpenForms API Calls

  1. Go to Integrations > Web API and select Copy key from the ... menu of the key you'd like to use to copy the API key to your clipboard. 
     copy key.png
  2. Select the API documentation link to enter the API explorer.
    Alternatively, if you are a third-party developer, ask an OpenForms admin to generate a key for you and send you a link to the API explorer. 
  3. Make sure you're viewing the documentation for version of the API key that corresponds with your key. 
  4. Select Authorize to enter your API Key. 

    authorize.png
    You can now test calls on your organization's data.
  5. Browse through the available calls to find one you'd like to use. Calls are categorized by the OpenForms feature they are relevant to and their action (such as "GET," "DELETE," and so on). They are presented as URL endpoints accompanied by plain language explanations. Select an endpoint to reveal a list of of parameters and other options. 
    form call.png
  6. Click Try it out to apply any parameters you'd like to use and test that call.
     
    parameter.gif
    (In the example above, a call to receive a list of published forms is modified to receive a list of draft forms instead with the status parameter.)
  7. Perform a trial run of the call by clicking execute. Be careful, executing calls from the "try it out" menu is a live action, and some API calls (anything not marked GET) will make changes to your data.

  8. Check the server results panel for the outcome of your call.

    Server Results.png
    In the example above, a call draft forms has returned 369 results.

If the call has worked as expected, you can implement it into your application code.

Implement OpenForms API Calls into External Code

How you implement OpenForms API calls into your code is a matter of personal preference, and dependent on the coding language you use.

You may, however, find an example project useful when getting started. We've prepared a walkthrough and sample code in C# to get you going. Find it here: 
Was this helpful?

Related topics