Only admins can access the API screen in OpenForms. If you’re not an admin, you can still use the API itself.
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
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.
From the main menu, go to Admin > Integrations > API.
Choose Create Key.
Choose the API version and select its permissions.
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.
Manage API keys
As you create API keys, they'll be listed in the OpenForms API screen. You can select any of your API keys to change the permissions associated with them.
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.
The API is regularly updated with new features and, sometimes, changes to the structure of requests. We keep previous versions active to ensure back-compatibility. 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
- Hover over an API Key in the OpenForms API screen to reveal a copy icon. Select this to copy the API Key to your clipboard.
- 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.
- Make sure you're viewing the documentation for version of the API key that corresponds with your key.
- Select Authorise to enter your API Key.
You can now test calls on your organization's data.
- 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.
- Click try it out apply any parameters you'd like to use and test that call.
(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.)
- 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.
Check the server results panel for the outcome of your call.
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: