Forms API

Content

This guide provides information on how to interact with the Forms REST API of Bloom Enterprise.

How to use it?

Item	Value
BASE_URI	http://SERVER_IP/restapi/v2/
RESPONSE_FORMAT	JSON

Attention

If the integration you are trying to develop will require pooling Bloom Enterprise’s REST API, you should use WebSockets instead. Please contact Q-Better’s team to know more details.

Forms Templates

List Existing Forms Templates

Item	Value
Name	List Existing Forms Templates
URL	BASE_URI/forms
HTTP Method	GET
Response Data	Fetches the list of existing forms templates

Responde Example

JSON
{
  "success": boolean,
  "forms": [
	{
	  "id": string,
	  "name": string,
	  "questions": {
      "before": [{
        "id": string,
        "selected" : boolean,
        "question": string,
        "expanded": boolean,
        "anonymize": boolean,
        "anonymize_in_days": int,
        "visible_on": {
          "ticket_kiosks": boolean,
          "virtual_ticket": boolean,
          "appointments": boolean,
          "concierge": boolean,
          "extender": boolean,
          "qm_pad": boolean,
          "card_reader": boolean,
          "eticket": boolean
        },
        "staff_permissions": {
          "visible": boolean,
          "editable": boolean
        },
        "depends_on": {
          "has_dependency": boolean,
          "question": string,
          "answer": string
        },
        "config": string,
        "qat_id": string,
        "required": boolean
      }],
      "during": [{ ... }],
      "end": [{ ... }]
    },
	},
	{...}],
  "fields": [
    [
      "id": string,
      "name": string,
      "type": int,
      "config": {
          "mask": int,
          "length": string
      },
      "permanent": boolean,
      "expanded": boolean,
      "selected": boolean
    ],
    {...}
  ]
}

Detail Form Template

Item	Value
Name	Details Form Template
URL	BASE_URI/forms/form_id
HTTP Method	GET
Response Data	Returns the details of a specific form template

Request options

Item	Value
form_id	Needs to be a UUID string.

Responde Example

JSON
{
  "success": boolean
  "role": {
    "id": string,
    "name": string,
    "selected": boolean,
    "questions": {
      "before": {
        "1": {
          "id": string,
          "selected": boolean,
          "question": string,
          "expanded": boolean,
          "anonymize": boolean,
          "anonymize_in_days": int,
          "visible_on": {
            "ticket_kiosks": boolean,
            "virtual_ticket": boolean,
            "appointments": boolean,
            "concierge": boolean,
            "extender": boolean,
            "qm_pad": boolean,
            "card_reader": boolean,
            "eticket": boolean
          },
          "staff_permissions": {
            "visible": boolean,
            "editable": boolean
          },
          "depends_on": {
            "has_dependency": boolean,
            "question": string,
            "answer": string
          },
          "config": string,
          "qat_id": string,
          "required": boolean
        },
        {...}
      },
      "during": [],
      "end": []
    }
  }
}

Create Form Template

Item	Value
Name	Create form template
URL	BASE_URI/forms
HTTP Method	POST
Response Data	Returns success of operation and the id of the new form template

Config elements

Item	Meaning
question_order	Question order index starts on 0

Request body example

JSON
{
  "name": string,
  "selected": boolean,
  "questions": {
    "before": [
      {
        "id": string,
        "selected": boolean,
        "question": string,
        "expanded": boolean,
        "anonymize": boolean,
        "anonymize_in_days": int,
        "visible_on": {
          "ticket_kiosks": boolean,
          "virtual_ticket": boolean,
          "appointments": boolean,
          "concierge": boolean,
          "extender": boolean,
          "qm_pad": boolean,
          "card_reader": boolean,
          "eticket": boolean
        },
        "staff_permissions": {
          "visible": boolean,
          "editable": boolean
        },
        "depends_on": {
          "has_dependency": boolean,
          "question": string,
          "answer": string
        },
        "config": string,
        "qat_id": string,
        "required": boolean,
        "question_order": int
      },
      {...}
    ],
    "during": [],
    "end": []
  }
}

Responde Example

JSON
{
  "success": boolean,
  "id": string
}

Update Form Template

Item	Value
Name	Updates existing form template
URL	BASE_URI/forms/form_id
HTTP Method	UPDATE
Response Data	Returns success of operation and the id of the form template

Request options

Item	Value
form_id	Needs to be a UUID string.

Config elements

Item	Meaning
question_order	Question order index starts on 0

Request body example

JSON
{
  "name": string,
  "selected": boolean,
  "questions": {
    "before": [
      {
        "id": string,
        "selected": boolean,
        "question": string,
        "expanded": boolean,
        "anonymize": boolean,
        "anonymize_in_days": int,
        "visible_on": {
          "ticket_kiosks": boolean,
          "virtual_ticket": boolean,
          "appointments": boolean,
          "concierge": boolean,
          "extender": boolean,
          "qm_pad": boolean,
          "card_reader": boolean,
          "eticket": boolean
        },
        "staff_permissions": {
          "visible": boolean,
          "editable": boolean
        },
        "depends_on": {
          "has_dependency": boolean,
          "question": string,
          "answer": string
        },
        "config": string,
        "qat_id": string,
        "required": boolean,
        "question_order": int
      },
      {...}
    ],
    "during": [],
    "end": []
  }
}

Responde Example

JSON
{
  "success": boolean,
  "id": string
}

Delete Form Template

Item	Value
Name	Delete Form Template
URL	BASE_URI/forms/form_id
HTTP Method	DELETE
Response Data	Returns success of operation

Request options

Item	Value
form_id	Needs to be a UUID string.

Responde Example

JSON
{
  "success": boolean
}

Delete Question Inside a Form Template

Item	Value
Name	Delete Question Inside a Form Template
URL	BASE_URI/forms/form_id/questions/question_id
HTTP Method	DELETE
Response Data	Returns success of operation

Request options

Item	Value
form_id	Needs to be a UUID string.
question_id	Needs to be a UUID string.

Responde Example

JSON
{
  "success": boolean
}

Question Answer Types

List Existing Question Answer Types (Questions)

Item	Value
Name	List Existing Question Answer Types (Questions)
URL	BASE_URI/qats
HTTP Method	GET
Response Data	Fetches the list of existing question answer types

Config elements

Item	Meaning
to	Used only for Questions of Type Rating
mask	Used only for Questions of Type Text (Format type: 2 - Numeric; 3 - Alpha; 4 - Alphanumeric; 5 - Custom)
length	Used only for Questions of Type Text to set Max. length of question answer
regex	Used only for Questions of Type Text with custom format (mask 5)
example	Valid example using the regex above. Used only for Questions of Type Text with custom format (mask 5)

Responde Example

JSON
{
    "success": boolean,
    "question_answer_types": [
        {
            "id": string,
            "name": string,
            "type": int,
            "config": {
                "mask": int,
                "length": string
            },
            "permanent": boolean,
            "expanded": boolean,
            "selected": boolean
        },
        {...}
    ]
}

Create Question Answer Type

Item	Value
Name	Create Question Answer Type
URL	BASE_URI/qats
HTTP Method	POST
Response Data	Returns success of operation and the new question answer type

Config elements

Item	Meaning
to	Used only for Questions of Type Rating
mask	Used only for Questions of Type Text (Format type: 2 - Numeric; 3 - Alpha; 4 - Alphanumeric; 5 - Custom)
length	Used only for Questions of Type Text to set Max. length of question answer
regex	Used only for Questions of Type Text with custom format (mask 5)
example	Valid example using the regex above. Used only for Questions of Type Text with custom format (mask 5)

Type elements

Item	Meaning
1	Multiple Choice Answer
2	Single Choice Answer
3	Rating Answer
4	Text Answer

Request body example

JSON
[
    {
        "config": "{
          "mask": int,
          "length": string
        }",
        "expanded": booelan,
        "id": string,
        "name": string,
        "permanent": booelan,
        "selected": booelan,
        "type": int,
        "temp": booelan,
        "edited": booelan
    }
]

Responde Example

JSON
{
    "success": boolean,
    "qats": [
      {
        "new": {
          "id": string,
          "name": string,
          "type": int,
          "config": string,
          "permanent": boolean,
          "questions": string,
          "question_answers": string,
        },
        "old": { ... }
      }
    ]
}

Update Question Answer Type

Item	Value
Name	Update Question Answer Type
URL	BASE_URI/qats/qat_id
HTTP Method	UPDATE
Response Data	Returns success of operation and the new and old question answer type

Request options

Item	Value
qat_id	Needs to be a UUID string.

Config elements

Item	Meaning
to	Used only for Questions of Type Rating
mask	Used only for Questions of Type Text (Format type: 2 - Numeric; 3 - Alpha; 4 - Alphanumeric; 5 - Custom)
length	Used only for Questions of Type Text to set Max. length of question answer
regex	Used only for Questions of Type Text with custom format (mask 5)
example	Valid example using the regex above. Used only for Questions of Type Text with custom format (mask 5)

Type elements

Item	Meaning
1	Multiple Choice Answer
2	Single Choice Answer
3	Rating Answer
4	Text Answer

Request body example

JSON
[
    {
        "config": "{
          "mask": int,
          "length": string
        }",
        "expanded": booelan,
        "name": string,
        "permanent": booelan,
        "selected": booelan,
        "type": int,
        "temp": booelan,
        "edited": booelan
    }
]

Responde Example

JSON
{
    "success": boolean,
    "qats": [
      {
        "new": {
          "id": string,
          "name": string,
          "type": int,
          "config": string,
          "permanent": boolean,
          "questions": string,
          "question_answers": string,
        },
        "old": { ... }
      }
    ]
}

Delete Question Answer Type

Item	Value
Name	Delete Question Answer Type
URL	BASE_URI/qats/qat_id
HTTP Method	DELETE
Response Data	Returns success of operation

Request options

Item	Value
qat_id	Needs to be a UUID string.

Responde Example

JSON
{
  "success": boolean
}

Answer to Forms

List Answers from a Ticket

Item	Value
Name	List Answers from a Ticket
URL	BASE_URI/forms/form_id/answers/ticket_id
HTTP Method	GET
Response Data	Fetches the list of existing questions answers from a ticket

Request options

Item	Value
form_id	Needs to be a UUID string.
ticket_id	Needs to be a UUID string.

Responde Example

JSON
{
    "success": boolean,
    "answers": [
        {
          "answer_response_1": string,
          "answer_response_2": string,
          ...
        }
    ]
}

Add/Update Answer to a Ticket

Item	Value
Name	Add/Update Answer to a Ticke
URL	BASE_URI/forms/form_id/answers
HTTP Method	POST
Response Data	Fetches the list of existing question answer types

Request options

Item	Value
form_id	Needs to be a UUID string.

Device Type elements

Item	Meaning
1	Ticket Dispenser
6	Extender
13	Tablet Kiosk
14	Concierge
15	Virtual Concierge
17	Backoffice (Appointments)
18	E-ticket
98	QM-PAD

Attendance Time elements

Item	Meaning
0	Before calling the ticket
1	While answering a ticket
2	After answering a ticket

JSON
{
  "answers": [
    {
      "qat_id": string,
      "question": string,
      "question_answer": string,
      "question_text": string,
      "answer_text": string
    },
    {...}
  ],
  "device_type": int,
  "ticket_id": string,
  "has_survey": boolean,
  "attendance_time": int
}

Responde Example

JSON
{
    "success": boolean,
}

Utility to Forms

Get Checkin Question

Item	Value
Name	Get Checkin Question
URL	BASE_URI/forms/utility/getCheckinQuestion?lang=lang
HTTP Method	GET
Response Data	Returns the question used to check-in appointments

Request options

Item	Value
lang	Needs to be a string.

Attention

The mask-repeat attribute is the same as the config length. Which establish the maximum size of the answer, 0 mean unlimited.

Mask Type elements

Item	Meaning
2	Numeric
3	Alpha
4	Alphanumeric
5	Custom

Type elements

Item	Meaning
1	Multiple Choice Answer
2	Single Choice Answer
3	Rating Answer
4	Text Answer

Responde Example

JSON
{
  "success": boolean,
  "questions": [
    {
      "mask": int,
      "mask-repeat": int,
      "question": string,
      "type": int,
      "name": string,
      "answer": string,
      "qat_id": string
    }
  ]
}

Get Communication Question

Item	Value
Name	Get Communication Question
URL	BASE_URI/forms/utility/getCommunicationQuestion
HTTP Method	GET
Response Data	Returns the communication questions used to alert customers for appointments

Attention

The mask-repeat attribute is the same as the config length. Which establish the maximum size of the answer, 0 mean unlimited.

Mask Type elements

Item	Meaning
2	Numeric
3	Alpha
4	Alphanumeric
5	Custom

Type elements

Item	Meaning
1	Multiple Choice Answer
2	Single Choice Answer
3	Rating Answer
4	Text Answer

Responde Example

JSON
{
  "success": boolean,
  "questions": [
    {
      "mail": {
        "qat_id": string,
        "mask": int,
        "mask-repeat": int,
        "answer": string,
        "type": int,
        "question": string,
        "name": string
      },
      "phone": {
        "qat_id": string,
        "mask": int,
        "mask-repeat": int,
        "answer": string,
        "type": int,
        "question": string,
        "name": string
      }
    }
  ]
}

Get Customer Identification Question

Item	Value
Name	Get Customer Identification Question
URL	BASE_URI/forms/utility/getCustomerIdentificationQuestion?lang=lang
HTTP Method	GET
Response Data	Returns the question used for the customer to login (usually email or phone)

Request options

Item	Value
lang	Needs to be a string.

Attention

The mask-repeat attribute is the same as the config length. Which establish the maximum size of the answer, 0 mean unlimited.

Mask Type elements

Item	Meaning
2	Numeric
3	Alpha
4	Alphanumeric
5	Custom

Type elements

Item	Meaning
1	Multiple Choice Answer
2	Single Choice Answer
3	Rating Answer
4	Text Answer

Responde Example

JSON
{
  "success": boolean,
  "questions": [
    {
      "qat_id": string,
      "mask": int,
      "mask-repeat": int,
      "answer": string,
      "type": int,
      "question": string,
      "name": string,
      "required": boolean
    }
  ]
}

Content​

Forms Templates​

List Existing Forms Templates​

Detail Form Template​

Create Form Template​

Update Form Template​

Delete Form Template​

Delete Question Inside a Form Template​

Question Answer Types​

List Existing Question Answer Types (Questions)​

Create Question Answer Type​

Update Question Answer Type​

Delete Question Answer Type​

Answer to Forms​

List Answers from a Ticket​

Add/Update Answer to a Ticket​

Utility to Forms​

Get Checkin Question​

Get Communication Question​

Get Customer Identification Question​

Content

Forms Templates

List Existing Forms Templates

Detail Form Template

Create Form Template

Update Form Template

Delete Form Template

Delete Question Inside a Form Template

Question Answer Types

List Existing Question Answer Types (Questions)

Create Question Answer Type

Update Question Answer Type

Delete Question Answer Type

Answer to Forms

List Answers from a Ticket

Add/Update Answer to a Ticket

Utility to Forms

Get Checkin Question

Get Communication Question

Get Customer Identification Question