Rest API usage – add forms

Introduction to API

Accessing API

URL: forms.beonder.com/api

Get parameter: api_key=**API-KEY**

Request your API key at Beonder support. Each key has different restrictions and is limited to one license.

Content types

It supports the request/response formats; XML, JSON and serialized PHP. By default, the class will check the URL and look for a format either as an extension or as a separate segment. If format is not defined, JSON is used as default. We generally use JSON in our documentation examples.

Usage parameter: format=*type string*

Response format

Successful request:

{ “success”: “true”, “data”: { }, “message”: null }

Failed request:

{ “success”: “false”, “data”: null, “message”: “Error xyz has occurred” }

POST parameters

It is possible to add customer, location and form in one request by combining all fields as documented.

Add customer:

customer_title:

Strict search on customer title. If it does not exist, it will be added.

Add location:

release_id:	Release ID which contains
slug:	Copy shared form and settings and create a new slug. Useful when adding user data.

Add custom data (optional):

data:

Array of fields (json).

Example: {“startdate”:”2022-01-01″,”moderator.approved”:”1″}
Above array keys are based on field*dot*subfield (question.answer).

Add form:

release_id (required):	Release ID which contains (int)
customer_id (required):	If customer_title is used this field is optional (int)
location_id (required):	If location_title is used this field is optional (int)
assigned (optional):	User group title (string). Example: main group / team 1
scheduled (optional):	User name (string)

Create slug (optional):

slug (required):

Copy shared form and settings and create a new slug. Useful when adding user data.

This will return a slug as data. Please view the response.

Usage of the slug: forms.beonder.com/form/start/*SLUG*

Response:

Success:	true/false (bool)
Message:	Response text (string)
Data:	(string)

Short introduction to “form sharing”

Form sharing is a functionality to share ‘releases’ for public usage. Restrictions can be added by using customer, location and group related post values. You can open a shared form by using the slug. The moment an ‘anonymous’ user opens a slug and starts a form, Beonder will create a new personal link to allow further access. If an email address is known, the anonymous user receives the link per email. In this way data is still accessible once the browser is closed.

Some extra options to share a form: Introduction text, introduction email, thank you / download page (redirect).

Create slugs for form sharing by passing arguments to our API.

Usage URL: forms.beonder.com/api/share_form/?api_key

Explanation of slug generation

Create a new slug based on an existing slug that is provided by your Admin. Each slug contains specific settings such as an invitation text and a thank you page.

Admin adds a release “my first form” (=questionnaire)
Admin adds sharing slug through Beonder software:tVLpNwiv.
Call API and create a new slug MiXdbjGm based on (the settings of) tVLpNwiv. Provide information such as customer/location (and assigned group).
User opens forms.beonder.com/start/MiXdbjGm.
User clicks start/next:
Customer is added if not exists
Location is added if not exists
Group is added if not exists
Form created (one per request).

On successful form creation

After creation your admins or team users can view stored forms under each customer and location hierarchy.

You can generate team hierarchy by using the a ‘slash’ as a subgroup. So you can manage main groups and separate team.

Usage statistics

In progress, but already contains:

Slug creation date.
Form creation date.
Form edited date(s).
Form finished date.

Diagram for slug generation (through API)

Starting with releases at the left top, sharing a form by slug and generating new slugs by parent-slug through API. Each time a student starts filling in a form by using the slug a new form is created.

Assigned – Automatically add groups / teams

Hierarchy is added if the assigned value is posted through API.

Post example (PHP)

$url = ‘https://forms.beonder.com/api/share_form?api_key=*API_KEY*;

$data = array(‘slug’ => *slug*, ‘assigned’ => ‘External company/Region/Team 1’, ‘customer_title’ => ‘Warner Inc.’, ‘location_id’ => ‘London’, ‘data’ => array(‘contract’ => ‘Yearly’);

// use key ‘http’ even if you send the request to https://…

$options = array(

‘http’ => array(

‘header’ => “Content-type: application/x-www-form-urlencoded\r\n”,

‘method’ => ‘POST’,

‘content’ => http_build_query($data)

)

);

$context = stream_context_create($options);

$result = file_get_contents($url, false, $context);

Reports

Single form result through thank you page via API

Short introduction to “single form result”

Each form might contain reports in Word (docx) format. If a shared form has a custom thank you page* an anonymous user won’t be able to download reports directly from forms.beonder.com, but our software will add an encrypted key to the url. You can use the key get-parameter to retrieve form information through our API.

* thank you page: provided by an administrator to redirect users after finishing to a specific page.

Create slugs for form sharing by passing arguments to our API.

Usage URL: forms.beonder.com/api/form/?api_key

GET values:

Required: One of the following values:

key: Encrypted form key

Response:

Success: true/false (bool)

Message: Response text (string) or empty value

Data: Array with attachments, notes, calculations, reports (array)

Multiple form results by using widgets

Short introduction to “widgets”

Our software contains widgets on different levels depending on the settings per license. An administrator is in control of adding widgets to their dashboard(s)/result pages.

Get widget results by using our API

Usage URL: forms.beonder.com/api/results/?api_key

POST values:

Optional: Filter results by release or shared slug:

release_id: Release ID (int)

slug: Shared form slug (single as string, multiple* in json array)

* multiple slugs will do an exact match (if all are true / AND)

Optional: Customer or location id

customer_id: Get results on customer level by customer id.

location_id: Get results on location level by location id.

Optional: Customer title and location title

customer_title: Get results by strict search on customer title

location_title: Get results by strict search on location title and parent (customer_title)

Optional: Filter by assigned group

assigned: Group titles as array

Optional: Input data

data: Filter results by input data. Use question.answer = *value*.

Response:

Success: true/false (bool)

Message: Response text (string) or empty value

Data: widgets (array)