Skip to content

Form data API

Overview

Interaction Designer Form data API provides access to data that has been submitted by visitor through interactions.

List form submissions

It is common use to be able to fetch form submissions from a given interaction to some external system. This API allows you to fetch form submissions with optional filter parameters.

Endpoint: 

1
GET https://interactionbuilder.giosg.com/api/orgs/<organization_id>/forms/data?interactionUuid=<interaction_uuid>

Endpoint with optional filtering parameters: 

1
GET https://interactionbuilder.giosg.com/api/orgs/<organization_id>/forms/data?interactionUuid=<interaction_uuid>&from=<start_time>&to=<end_time>&jsonEq=<json_equals_filter>&jsonLike=<json_like_filter>&orderDesc=<ordering>

Getting interaction ID

You may get interaction ID (interactionUuid) either by using Interactions API or from the Interaction Designer UI by clicking the name of the interaction in the design view and copying the interaction ID from opened popup.

Opening ID JS Editor

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import requests

API_TOKEN = "<api token>"
INTERACTION_ID = "<interaction id>"
ORGANIZATION_ID = "<organization id>"
url = "https://interactionbuilder.giosg.com/api/orgs/{}/forms/data?interactionUuid={}".format(ORGANIZATION_ID, INTERACTION_ID)
response = requests.get(url, headers={
    'Authorization': 'Token {}'.format(API_TOKEN)
})
response.raise_for_status()
print(response.json())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const API_TOKEN = "<api token>";
const INTERACTION_ID = "<interaction id>";
const ORGANIZATION_ID = "<organization id>";
const url = `https://interactionbuilder.giosg.com/api/orgs/${ORGANIZATION_ID}/forms/data?interactionUuid=${INTERACTION_ID}`;
const response = await fetch(url, {
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.json());

Request parameters

Listing form submissions always requires interactionUuid parameter. Other filters are optional.

Parameter Type Required Description
interactionUuid string Required UUID of the interaction whose form data submissions to get
url string Optional Form submission url
from date/time Optional Earliest time of form submission in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z
to date/time Optional Latest time of form submission in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z
jsonEq object Optional Url encoded JSON object with filter parameters to match exactly
jsonLike object Optional Url encoded JSON object with filter parameters to match partially
orderDesc boolean Optional true if reasults should be ordered descendingly

Response

Attribute Type Description
id integer Fom submission ID
timestamp date/time Time of form submission
projectName string Name of the project
visitorId string Visitor ID
roomId string Always empty string
formdata object Form data object which contains input field values of submitted interaction form
triggerName string Name of the element that triggered the form submit
clickHistory array of strings Array of element names that were clicked before the form submit
url string Url where the interaction was shown and form submitted

formdata attribute

Form data API returns formdata attribute when you fetch submitted data. This attribute is always object but it's attributes depend on the fields that you have in your interaction. Objects attributes may also change between submissions. If interaction data was submitted first time with input field myField and on later stage this field was removed, it won't be included in the formdata object. Types of attributes depend on the input type's you have in your interaction.

Element type Formdata attribute type description
Checkbox boolean true if checkbox selected, false otherwise
Radio button string Value of the radio button, for example "Yes" or "No"
Select string Value of the select, for example "Yes" or "No"
Text input string Value of the input, for example "John Doe"

For example if you have fields text input named "name" and a checkbox named "accept terms" in your interaction, formdata would look like below:

1
2
3
4
"formdata": {
    "name": "John Doe",
    "accept terms": true,
}

Delete a form submission

Sometimes it might be required that some of the form submissions need to be deleted, for example because of GDPR or if they contain incorrect data.

Endpoint: 

1
DELETE https://interactionbuilder.giosg.com/api/orgs/<organization_id>/forms/data/<form submission id>


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import requests

API_TOKEN = "<api token>"
SUBMISSION_ID = "<form submission id>"
ORGANIZATION_ID = "<organization id>"
url = "https://interactionbuilder.giosg.com/api/orgs/{}/forms/data/{}".format(ORGANIZATION_ID, SUBMISSION_ID)
response = requests.delete(url, headers={
    'Authorization': 'Token {}'.format(API_TOKEN)
})
response.raise_for_status()
print(response.status_code)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
const API_TOKEN = "<api token>";
const SUBMISSION_ID = "<form submission id>";
const ORGANIZATION_ID = "<organization id>";
const url = `https://interactionbuilder.giosg.com/api/orgs/${ORGANIZATION_ID}/forms/data/${SUBMISSION_ID}`;
const response = await fetch(url, {
    method: "DELETE",
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.status);

To delete form data row, first use form data listing API to get rows and their respective ID's and then make DELETE request to above endpoint. HTTP 200 OK response will be returned when request is successful.

Get count of form submissions

If you only need the count of form submissions it is better to use the dedicated API instead of manually counting rows in returned data. The count API allows filtering data in the same way as the listing of form submissions API does.

Endpoint: 

1
GET https://interactionbuilder.giosg.com/api/orgs/<organization_id>/forms/count?interactionUuid=<interaction_id>

Endpoint with optional filtering parameters: 

1
GET https://interactionbuilder.giosg.com/api/orgs/<organization_id>/forms/count?interactionUuid=<interaction_id>&from=<start_time>&to=<end_time>&jsonEq=<json_equals_filter>&jsonLike=<json_like_filter>


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import requests

API_TOKEN = "<api token>"
INTERACTION_ID = "<interaction id>"
ORGANIZATION_ID = "<organization id>"
url = "https://interactionbuilder.giosg.com/api/orgs/{}/forms/count?interactionUuid={}".format(ORGANIZATION_ID, INTERACTION_ID)
response = requests.get(url, headers={
    'Authorization': 'Token {}'.format(API_TOKEN)
})
response.raise_for_status()
print(response.json())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const API_TOKEN = "<api token>";
const INTERACTION_ID = "<interaction id>";
const ORGANIZATION_ID = "<organization id>";
const url = `https://interactionbuilder.giosg.com/api/orgs/${ORGANIZATION_ID}/forms/count?interactionUuid=${INTERACTION_ID}`;
const response = await fetch(url, {
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.json());

Request parameters

Getting form submission count always requires interactionUuid parameter. Other filters are optional.

Parameter Type Required Description
interactionUuid string Required UUID of the interaction whose form data submissions to get
url string Optional Form submission url
from date/time Optional Earliest time of form submission in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z
to date/time Optional Latest time of form submission in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z
jsonEq object Optional Url encoded JSON object with filter parameters to match exactly
jsonLike object Optional Url encoded JSON object with filter parameters to match partially

Response

Attribute Type Description
count integer Count of filter matching form submissions

Download form data as CSV file

Form submissions can be also downloaded as a CSV file for easy filtering, moving to another systems or for analysis purposes.

Endpoint: 

1
POST https://interactionbuilder.giosg.com/api/orgs/<organization_id>/forms/csv

Downloading form submissions can be filtered also. This endpoint however uses the POST request method and so the payload should be a JSON object. The attribute interactionUuid is required, other filters are optional.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import requests
import json

API_TOKEN = "<api token>"
INTERACTION_ID = "<interaction id>";
ORGANIZATION_ID = "<organization id>"
url = "https://interactionbuilder.giosg.com/api/orgs/{}/forms/csv".format(ORGANIZATION_ID)
payload = {
    "interactionUuid": INTERACTION_ID,
}
response = requests.post(url, data=json.dumps(payload), headers={
    'Authorization': 'Token {}'.format(API_TOKEN),
    'Content-Type': 'application/json',
})
response.raise_for_status()
print(response.json())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
const API_TOKEN = "<api token>";
const INTERACTION_ID = "<interaction id>";
const ORGANIZATION_ID = "<organization id>";
const url = `https://interactionbuilder.giosg.com/api/orgs/${ORGANIZATION_ID}/forms/csv`;
const payload = {
    interactionUuid: INTERACTION_ID
};
const response = await fetch(url, {
    method: "POST",
    body: JSON.stringify(payload),
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.json());

Request parameters

Parameter Type Required Description
interactionUuid string Required UUID of the interaction whose form data submissions to get
token string Required Your access token
url string Optional Form submission url
from date/time Optional Earliest time of form submission in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z
to date/time Optional Latest time of form submission in ISO-8601 format, eg. 2021-02-18T10:10:57.242Z
jsonEq object Optional Url encoded JSON object with filter parameters to match exactly
jsonLike object Optional Url encoded JSON object with filter parameters to match partially
orderDesc boolean Optional Order results descending

Example payload: 

1
2
3
4
5
6
7
8
9
{
    "projectUid": 9640,
    "from": "2020-09-09T21:00:00.000Z",
    "to": "2021-02-18T21:59:59.999Z",
    "jsonEq": "{\"marketing_email_type\":\"All emails\"}",
    "jsonLike": "{}",
    "orderDesc": "true",
    "token": "<your access token>"
}

Response

Response will be data in CSV format. Response will contain your interaction form fields much like the form data listing API, however in this case all rows will have all columns even if the interaction did not have the field defined at the time of submission. If field did not exist when form submission was made, it's value will be empty. The CSV data will also contain headers to indicate what every column represents.