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 get started? 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

Generate a Key 

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. 

  1. From the main menu, go to Integrations >  Web API.

  2. Choose Create API Key.

  3. Choose the API version and select its permissions.

    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. 

  4. Click 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.

You can also disable or delete individual keys at any time by clicking the '...' icon next to a key, and choosing disable or delete. 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. In the Web API screen, 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 API documentation to enter the API explorer.
    Alternatively, if you are are a third party developer, ask an OpenCities 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. Click an endpoint to reveal a list of of parameters and other options. 
    form call.png
  6. Click try it out 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