API Helpsheet

Learn everything you need to know about our API

What is the API?

Our API (Application Programming Interface) can be used to gain access and manipulate your forms collected data without having to login to the forms application within your browser. Here are some use cases for our API:

  • You could use the API to get your forms collected data into your IT systems.
  • You could use the API to display your forms collected data on a website.
  • You could use the API to share your collected forms data with other parties.
  • You can even use the API to change the data collected within forms.
  • You could construct your own application to have forms embedded within.

The API allows advanced users to programmatically access data. Developers are the intended audience for the API but anyone with a Formwize account can use the API facility.

 

API Basics

Our Application Programming Interface (API) acts as a software (forms) to software (any other software or system ) interface, allowing our forms software to communicate using a 'Pull' data fashion with any other software and systems. It is a set of functions and processes which allow other external ( external to our API ) applications and/or systems to access features or data from the forms service.

For example: the application actually uses an API to integrate Google Maps into forms for event invites to guide the recipient to the event via a geographically embedded Google map view.

‎ Picture 16

‎
‎Our API is mainly used as a 'Pull' mechanism, meaning, other applications or systems can 'Pull' data collected by forms into their domain for onward use or storage.

  • Our standard API is 'Read only' – you can only pull collected forms data out, you cannot create, update or delete data with the standard API. This will be covered later on within this topic.
  • Our API is REST based and offers asynchronous (pull the data on an ad hoc or timed basis but is not technically real-time) stateless access to forms data e.g. you could pull your collected data on a timed fashion such as every 10 seconds or 10 minutes.

It also does not 'Push' data (akin to a WebHook). The receiving application must initiate a 'Pull' request using a secure API account and key that we provide.

 

Why use API?

API’s are re-usable, secure and manageable. There are many benefits of using API which include:

  • Providing data in a format (e.g. JSON) which is clean, readable and in a programmatically accessible and usable format.
  • Providing up to date data views (not real-time or synchronous but asynchronous).
  • Providing correct data, as it pulls data from an authorised static endpoint source so the information is always valid.
  • Reduces the requirement to build custom software interfaces.
  • Saves manual data exchange which is subject to transposition errors and is time consuming.

 

Who Will Generally Use the API?

Our API is a feature that developers tend to use. Our API is a 'Pull' mechanism where the source system (forms) can pass data into a target platform. As the forms team don’t control external systems, we give the API 'keys' to your developer to allow them to unlock the forms data and pull it into their target system or application(s).

Note! A 'Pull' mechanism is the opposite of a Webhook. A Webhook generally pushes data from a source system into another target system.

 

What do I need to use the API ?

Note! Firstly, you may not need to use the API if you just need visual or limited needs access to another accounts forms and collected form data. You can request 'Delegate' access, where a delegator (the origin account owner) provides GUI login access to you from within their account giving you vision (full read & write editing) of their forms and their collected form data via the GUI browser login.

If you have established that you need API access, you now need to setup the API access credentials within your forms account.

You can setup both API & Delegate access; they are not mutually exclusive.

  • 'Delegate' use means providing full read & write access into your forms and collected data with another forms user via the forms GUI.
    ‎ When a user logs in to their account via a browser, they can also see (and edit) your forms and data if you have given them delegated access into your account.
    ‎
    Hint! A delegate cannot access the delegators API Key.

     

  • API use provides RESTful & stateless access into your form collected data programmatically.
    ‎
    ‎RESTful & Stateless basically means you can access the forms and data at point in time of your choosing. The forms and data will change and each API access may reveal new or edited data at the point in time when you access. Stateless means you connect via the API and no lasting changes or connection with the data is maintained e.g. this could mean using the API to read data at a point in time without any impact to the data being viewed.
    ‎‎

If you have a forms account, you can self set yourself up with an API Developer account to allow you, or another application, to have access to your collected data e.g. asynchronous access to survey stats could be web presented as a visual graph as results come in.
‎ ‎

Is API Setup & Use Free?

Everything has a cost in life. Anything programmatic involves dialogue and we are happy to advise you for free on the API use or suitability. We obviously rely on you to organise integration or project interfaces with your target systems that will ingest any data. We can advise on the boundaries of use.

There is therefore a cost to use this service. Data transferring from our systems uses computational processing power, memory and network resource. All of these resources have a cost. Please contact us for costs which are dependent on the scale of your API use.
‎‎
‎To allow more than one developer secure API access (e.g. if you have a team of developers requiring individual secure access that can be audited) please email our support team: support@formwize.com

Our support team can then elevate your forms account type to have multiple API users (developers) where we set a 'Max Accounts=X'. Where 'X' equals the number of API developers that you may you need to provide API access to.

You can share your API access credentials with your developers, but you would not be able to audit their use individually.

 

API Commands

The following API commands will return a list of different datasets from your accounts forms:

GetSingleTicket: This command displays the survey submission for one singular ticket number.

GetQuestionsData: This command will return single result data for a graphable survey question.

GetFile: This command will display the forms which may be accessed using this unique apiKey.

GetResults: This command will return specific survey submissions. The default action is to get all tickets unless modified by the parameters below.

hello: required any apiKey

GetForm: This command will display the forms which may be accessed using this unique apiKey.

GetResults4: This command will return specific survey submissions. The default action is to get all tickets unless modified by the parameters below. Limiting action is enforced if recordcount of request exceeds limits.

GetAllForms: This command will display the forms which may be accessed using this unique apiKey.

 

API Return Message Codes

Our API returns standard REST error codes. The codes returned will help you debug any failures when building:

2xx: Success

  • 200 OK: Everything is OK, I'm returning what you asked for.

3xx: Redirects

  • 301 Moved Permanently: Anything maintaining links to this resource should update the links to the new location.
  • 302 Found: Temporarily available at the new location.

4xx: Client Error

  • 400 Error: General error condition, such as malformed input data.
  • 401 Unauthorized: You need to identify yourself before the request will be able to continue.
  • 403 Forbidden: You have been identified but do not have permission to access this resource or run the requested action.
  • 404 Not Found: The requested resource does not exist.
  • 405 Not Allowed: The requested verb is not allowed for this resource.

5xx: Server Error

  • 500 Error: General or Unknown error.
  • 503 Service Unavailable: Usually indicates app server or database is unavailable.

 

Special Characters Handling within API

When pulling data from the API, special characters are sanitised and will appear in the JSON output, which will cause no potential errors.

All reserved characters are properly escape:

  • Backspace is replaced with: \b
  • Form feed is replaced with: \f
  • New line is replaced with: \n
  • Carriage return is replaced with: \r
  • Tab is replaced with: \t
  • Double quote is replaced with: \"
  • Backslash is replaced with: \\

Any Javascript injection attempts are trapped and flagged up as: <invalid tag>

 

See Also

  1. API Examples