API Examples

Learn the use cases with API

‎‎Self Enabling API Access

'User 1' owns an account and wishes to share their collected form data with other applications from any of their forms. The data held in their account can be shared, via the API, with a target system e.g. ServiceNow or on a Web Dashboard.

‎‎Form data can be 'pulled' out for a particular form (each form has a unique number) or even for an individual form entry (each entry also has an individual number; entries are also known as tickets) or ranges of entries and can be 'pulled' out e.g. using date or time ranges or ticket number ranges (The API supports extraction of data using EPOCH time).
‎ ‎
‎‎This picture shows 'User 1' self-enabling API access within their account (a 'D' for 'Developer' account has been self created by 'User 1' within their account) :


Delegation with API

'User 1' owns an account and wishes to share their forms and collected form data from their account with another colleague named 'User 2' (e.g. 'User 1' may be going on vacation).
‎‎
‎‎A one-off annual charge is levied against the Delegator ('User 1') and delegate ('User 2') for creating and using a Delegated (N) Account. This charge made to allow for data processing and data transference (there is no charge for actual data amounts in megabyte or gigabyte terms or how often the data is pulled from their forms).

Note! You may only ever need one API Developer account setup to access form data via the API.

‎If you wish to segregate API access per application, you could create multiple API secret tokens to allow different API consumers (applications) with separate tokens. This will allow unique API access tokens to be created pertaining to each application to be dedicated without interfering with an API operation for a separate API project or application.

 

How to use API?

Each account has a unique API key (sometime referred to as a Token) which is analogous to a door key where the API key lets you into your forms and their collected data. If you lose your API key (or someone obtains your key) you can generate a new Key by pressing 'Refresh Token' to get a new key:

 

To get an API key, you would need to DIY create a 'D' for Developer account - there are two types of accounts: developer (D) and Delegate (N). For API access you would need to create a Developer account.
‎
‎To do this under your profile go to ‘Account’ \ ‘Edit Account’ and then choose the option ‘Add Sub Account’. Fill in the form with the relevant details of the person you are giving the developer rights to, and choose the ‘Developer Account’ option:

 

 

When you save these changes, the user will then have Developer rights within their account which will give them an API key. To get your API key, you need to go into the Account section within your account. By clicking on the 'Pencil' icon you will see your API key: 
‎

‎‎Warning! To keep your Key secure, we recommend refreshing the token every so often and ensure your run or play books take this refresh into consideration to allow the update of your target applications using this refreshed key. Do not let this key into the wild as it provides access to your data.

 

Next, you will need to go to the Formwize API screen, which allows you to use pre-formatted methods to ‘pull’ out information from the form entries. Each entry on a form automatically gets assigned a ticket number.‎

If you wish to retrieve the results of one ticket, click on ‘GetSingleTicket’.

  • Then you need to populate the fields with the correct information. In the ‘Query String Parameters’ input box, you can add your API Key by inputting ‘apikey’ in the first field and pasting the API key code into the following field.
  • ‎In the ‘surveyId’ field, copy the form number from your form and paste it into the field.
  • ‎‎‎Then enter the ticket number (each form entry has a unique ticket number) of the results you would like to retrieve. Then press ‘Send’.

This will then output the data in JSON (JavaScript Object Notation) format for results for the particular ticket number. This will allow you to take data that you collect and electronically transfer or map it into another system, for example a stock control system or ServiceNow.

 

API Limitations

There are some limitations to the use of API:

  • CRUD limitation: Our API can POST, GET, PUT, PATCH, and DELETE forms & data and those API verbs correspond to create, read, update, and delete (or CRUD). That said, for data safety reasons we offer 'Get' (read) out of the box only.

  • When you ‘pull’ (actually the http verb = 'GET') out data, you only have ‘read’ access. You cannot therefore create, update or delete the data. ‎If you want to place data (actually the http verb = 'PUT') or alter (actually the http verb = 'PATCH') or delete (actually the http verb = 'DELETE') data please contact our API team as this can be a complex and potentially destructive action on data.
  • Pulling too much data can also be a problem in terms of your onward tasks around filtering and can detrimentally affect your account speed as your instance may slow down.

For example, you could use EPOCH 'fromtime' time to pull all records. The epoch 'fromtime' entered above is requesting all records from Thursday, January 1, 1970 12:00:00 AM (all of them) so would return all records. A 'totime' would yield a much more reasonable set of data and may negate an error or timeout.