Webservices related to Forms

Form participation APIs can be used to build a link between ACTITO and forms that were not necessarily designed by ACTITO.

On the one hand, it can used to collect data coming from an external partner and submitting them to ACTITO in order to enrich a database, all while storing the source of information in a GDPR compliant way.

On the other hand, it is typically used when the form design is made by another platform. Answers given by profiles can be directly submitted in an ACTITO technical form by using the forms APIs.

Designing your ACTITO form in itself is not possible through the APIs. It has to be done in the ACTITO interface. For additional information on this subject, we invite you to read the chapter dedicated to forms.

However, forms API allow you to:

  • obtain the structure of a form

  • obtain the participation information of a profile

  • create and update participations to a form, all while applying enrichment rules

images/download/attachments/615292631/image2019-3-20_10-7-48.png

Preparing a form for API compatibility

Using APIs related to forms entails that your form will have to follow some constraints in order a successful use of webservices. Those constraints should be kept in mind when creating your form in the ACTITO interface.

Display name and translation

When creating your form by the means of ACTITO interface, if you choose multiple choice questions, you will have the possibility to define display values that differs from technical values. You can also translate these values depending on the language.

However, this notion is not supported in forms APIs. Only technical values, which remain the same whatever the language, can be obtained and submitted in return.

On the other hand, questions can be translated, as they will be associated with technical names.

Give your form proper technical names

Forms APIs make use of the technical names in order to submit data. It is the important to give clear and precise names to your questions, both for ease of use and to avoid any risk of error while setting up the APIs.

The short text that you can associate to each question while creating your form is used in reporting, but it is not the technical name, which must be added afterwards. To do so, click in the list of existing forms in the 'Active' tab. Click on the 'More' button then, in the dropdown menu, click on 'Define technical name'.

You will be able to define appropriate technical names both for the main survey and for each individual question.

Tip

If you included "Predefined questions", they will have a pre-defined technical name.

Database enrichment rules

Forms allow your contact to directly modify their profile information. During the creation of a form whose purpose is to be used the ACTITO APIs, it is necessary to define proper enrichment rules.

Indeed, one of the available enrichment rules consists in enriching the database if one specific page is submitted. However, the notion of page completion is not taken into account when APIs are used.

It is therefore necessary not to use this rule but instead to prefer the enrichment rule when "the participation to the form is complete".

For additional information about enrichment rules, we invite you to read the 'Enriching a database through a form'.

Forms APIs

Obtaining the structure of a form

As the design of your form in the ACTITO interface can be customized as you wish, both regarding the questions and their layout, you will need to learn how the structure of your form is transposed in the APIs.

To do so, you can use the method GET/entity{e}/form/{f}

The following parameters must be provided for this operation:

  • the entity to which the form belongs

  • the id of the form: this is either the technical name defined by you, or the technical id, which is a number auto-generated at its creation. In both cases, they can be retrieved in the ACTITO interface through the 'Define technical name' option, as explained above.

images/download/attachments/615292631/image2019-3-20_10-36-37.png

Example of request and of answer for this operation: (Download this example)

GET/entity{e}/form{f}
Curl call
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/form/72"
 
Response body
{
"id": 72,
"technicalName": "DemoDocForm",
"status": "ACTIVE",
"name": {
"localized": [],
"default": "Demo Doc"
},
"creationMoment": "20190214154537",
"updateMoment": "20190320104310",
"activeMoment": "20190220092641",
"closeMoment": null,
"participantParameters": {
"presence": "ALLOWED",
"table": "DemoDoc"
},
"questions": [
{
"id": 281,
"technicalName": "source",
"type": "String",
"valueType": "SINGLE",
"possibleValues": [],
"text": {
"localized": [],
"default": "source"
},
"other": {
"allowed": false,
"texts": []
},
"required": false
},
{
"id": 282,
"technicalName": "language",
"type": "Language",
"valueType": "SINGLE",
"possibleValues": [],
"text": {
"localized": [],
"default": "language"
},
"other": {
"allowed": false,
"texts": []
},
"required": false
},
{
"id": 296,
"technicalName": "where",
"type": "Country",
"valueType": "SINGLE",
"possibleValues": [
{
"value": "BE",
"text": {
"localized": [
{
"language": "FR",
"text": "Où habitez vous ?"
},
{
"language": "EN",
"text": "Where are you from ?"
}
],
"default": null
}
},
{
"value": "FR",
"text": {
"localized": [
{
"language": "FR",
"text": "Où habitez vous ?"
},
{
"language": "EN",
"text": "Where are you from ?"
}
],
"default": null
}
},
{
"value": "GB",
"text": {
"localized": [
{
"language": "FR",
"text": "Où habitez vous ?"
},
{
"language": "EN",
"text": "Where are you from ?"
}
],
"default": null
}
}
],
"text": {
"localized": [
{
"language": "FR",
"text": "Où habitez vous ?"
},
{
"language": "EN",
"text": "Where are you from ?"
}
],
"default": null
},
"other": {
"allowed": true,
"texts": [
{
"language": "FR",
"text": "Autre (spécifiez)"
},
{
"language": "EN",
"text": "Other (specify)"
}
]
},
"required": false
},
{
"id": 297,
"technicalName": "subscriptions",
"type": "String",
"valueType": "MULTI",
"possibleValues": [
{
"value": "Info",
"text": {
"localized": [
{
"language": "FR",
"text": "Quelles communications souhaitez vous recevoir ?"
},
{
"language": "EN",
"text": "Which communications do you wish to subscribe to ?"
}
],
"default": "Quelles communications souhaitez vous recevoir ?"
}
},
{
"value": "Newsletter",
"text": {
"localized": [
{
"language": "FR",
"text": "Quelles communications souhaitez vous recevoir ?"
},
{
"language": "EN",
"text": "Which communications do you wish to subscribe to ?"
}
],
"default": "Quelles communications souhaitez vous recevoir ?"
}
},
{
"value": "Offer",
"text": {
"localized": [
{
"language": "FR",
"text": "Quelles communications souhaitez vous recevoir ?"
},
{
"language": "EN",
"text": "Which communications do you wish to subscribe to ?"
}
],
"default": "Quelles communications souhaitez vous recevoir ?"
}
}
],
"text": {
"localized": [
{
"language": "FR",
"text": "Quelles communications souhaitez vous recevoir ?"
},
{
"language": "EN",
"text": "Which communications do you wish to subscribe to ?"
}
],
"default": "Quelles communications souhaitez vous recevoir ?"
},
"other": {
"allowed": false,
"texts": []
},
"required": false
},
{
"id": 304,
"technicalName": "AddressEmail",
"type": "EmailAddress",
"valueType": "SINGLE",
"possibleValues": [],
"text": {
"localized": [
{
"language": "FR",
"text": "Tapez votre adresse e-mail :"
},
{
"language": "EN",
"text": "Type your email address:"
}
],
"default": null
},
"other": {
"allowed": false,
"texts": []
},
"required": false
},
{
"id": 305,
"technicalName": "emailAddress",
"type": "EmailAddress",
"valueType": "SINGLE",
"possibleValues": [],
"text": {
"localized": [
{
"language": "EN",
"text": "E-mail address"
},
{
"language": "FR",
"text": "Adresse e-mail"
},
{
"language": "NL",
"text": "E-mailadres"
}
],
"default": "E-mail address"
},
"other": {
"allowed": false,
"texts": []
},
"required": null
}
]
}

The response you will obtain will contain the following elements:

Global parameters

  • "id": auto-generated technical id of the form

  • "technicalName": technical name of the form, that you could define, as explained previously

  • "status": states whether the form is still IN_DEFINITION, ACTIVE or if participation is no longer allowed (STOPPED)

  • "participantParameters": states whether the form is linked to a profile table

    • "presence": "FORBIDDEN" if the form is public and not linked to any database, "ALLOWED" if participation is linked to a profile database, "UNIQUE" if only one participation per profile is allowed

    • "table": the name of the associated profile table (if applicable)

Questions parameters

  • "id": auto-generated technical id of the question. It can be used to register participations through API

  • "technicalName": technical name of the form, that you could define, as explained previously. It can be used to register participations through API

  • "type": expected answer type (format). Download a file detailing the various possible answer types in forms: ValuesTypesForms.docx

  • "valueType": states whether only one answer is allowed (SINGLE) or if several answers are accepted (MULTI)

  • "possibleValues": this is an array listing the technical values of each possible answer (when answers are predefined, such as for checkboxes)

    • "localized": this is an array listing the translations of the question. This parameter is repeated for each possible answer value

  • "required": states whether the question is mandatory (true) or not (false)

Obtaining participation information

It is possible to retrieve diverse information about past participations to a form :

Obtaining participation details for a profile

To do so, you can use the operation GET/entity/{e}/form{f}/profile/{p}

The parameters used are the entity, the form id as well as the id of the profile whose interactions you want to obtain.

In addition to that, you can define filters:

  • on the creation or update date

  • include only complete or incomplete form participations. To obtain every participation (complete and incomplete), this parameter should be omitted

  • on the amount of displayed participations (the maximum and default value is 200)

Example of request and response for this operation: (Download this example)

GET/entity/{e}/form/{f}/profile/{p}
Curl call
curl -X GET --header "Accept: application/json" -d "{}" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/form/demodocform/profile/1147690"
 
Response body
{
"FormParticipations": [
{
"interactionId": 2482,
"FormId": {
"name": "DemoDocForm",
"id": 72
},
"AnswerForms": {
"AnswerGroup": [
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": [
{
"Question": {
"name": "language",
"questionId": 282
},
"Values": [
"FR"
],
"OtherValue": null
}
]
},
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": [
{
"Question": {
"name": "subscriptions",
"questionId": 297
},
"Values": [
"Newsletter"
],
"OtherValue": null
}
]
},
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": []
}
],
"Profile": "1147690",
"ParticipationMoment": "2019-03-20 11:28:48",
"Test": false,
"Completed": true
}
},
{
"interactionId": 2485,
"FormId": {
"name": "DemoDocForm",
"id": 72
},
"AnswerForms": {
"AnswerGroup": [
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": [
{
"Question": {
"name": "language",
"questionId": 282
},
"Values": [
"FR"
],
"OtherValue": null
}
]
},
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": [
{
"Question": {
"name": "subscriptions",
"questionId": 297
},
"Values": [
"Newsletter",
"Offer"
],
"OtherValue": null
}
]
},
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": []
}
],
"Profile": "1147690",
"ParticipationMoment": "2019-03-20 11:29:46",
"Test": false,
"Completed": true
}
},
{
"interactionId": 2478,
"FormId": {
"name": "DemoDocForm",
"id": 72
},
"AnswerForms": {
"AnswerGroup": [
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": [
{
"Question": {
"name": "language",
"questionId": 282
},
"Values": [
"FR"
],
"OtherValue": null
}
]
},
{
"QuestionGroupId": null,
"Answers": [
{
"Question": {
"name": "where",
"questionId": 296
},
"Values": [],
"OtherValue": "USA"
}
]
},
{
"QuestionGroupId": null,
"Answers": [
{
"Question": {
"name": "subscriptions",
"questionId": 297
},
"Values": [
"Info"
],
"OtherValue": null
}
]
},
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": []
}
],
"Profile": "1147690",
"ParticipationMoment": "2019-03-20 11:27:34",
"Test": false,
"Completed": true
}
},
{
"interactionId": 2487,
"FormId": {
"name": "DemoDocForm",
"id": 72
},
"AnswerForms": {
"AnswerGroup": [
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": [
{
"Question": {
"name": "language",
"questionId": 282
},
"Values": [
"FR"
],
"OtherValue": null
}
]
},
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": []
},
{
"QuestionGroupId": null,
"Answers": []
}
],
"Profile": "1147690",
"ParticipationMoment": "2019-03-20 11:31:12",
"Test": false,
"Completed": true
}
}
]
}

Obtaining the details of a single participation

It is possible to obtain the detail of a specific profile through the operation GET/entity/{e}/form{f}/interaction{i}

To do so, you will need to provide the entity, the form id and the participation technical id as parameters. The participation id can be obtained in various ways:

  • it is given as response when you submit a participation through API

  • it is given in the list of participations obtained through the previous operation.

The response received will be similar to that of the previous call, except that it will only contain the details of one participation.

Creating a form participation

It is possible to directly submit a form participation through API, especially if the form filled in by the profile was designed on another system, but you want the collected data to be stored in ACTITO.

In such a case, use the operation POST/entity/{e}/form{f}/interaction

The parameters for this operation are:

  • the entity on which the form is stored

  • the id of the form (technical name or auto-generated id)

  • the answers to the questions of the form, as JSON code

  • data collections parameters ("source", "way" and "date"), which allow you to specify how this information was obtained. This information is not required but stand as a good practice regarding GDPR.

images/download/attachments/615292631/image2019-3-20_15-0-55.png

The JSON code which make up the body of the request must be structured in the following way:

  • The "AnswerGroup" parameter is made of a list of "Answers" attributes, which correspond to 'questions-values' pairs found in the form.

    • "Question" is made of a "name" attribute, which is the technical name of the question.

    • "Values" containing the value(s) of the answer(s) to the question.

  • "Completed" must be set as "true" if the form was entirely completed. This a technical question.

  • "Test" must be set as "false" unless it is a test participation

  • "Profile" is the technical id of the profile (profileId). It must be specified to link the participation to a profile in case the form does not have any question based on a key attribute nor any enrichment rule that would allow to link the participation to a profile.

Example of a request including JSON code and its answers: (Download this example)

POST/entity/{e}/form/{f}/interaction
Curl call
 
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"AnswerGroup\": [{
\"Answers\": [{
\"Question\": {
\"name\": \"source\"
},
\"Values\": [
\"Register\"
]
}]
},
{
\"Answers\": [{
\"Question\": {
\"name\": \"language\"
},
\"Values\": [
\"EN\"
]
}]
},
{
\"Answers\": [{
\"Question\": {
\"name\": \"where\"
},
\"Values\": [
\"FR\"
]
}]
},
{
\"Answers\": [{
\"Question\": {
\"name\": \"AddressEmail\"
},
\"Values\": [
\"jane.doe@actito.be\"
]
}]
},
{
\"Answers\": [{
\"Question\": {
\"name\": \"subscriptions\"
},
\"Values\": [
\"Offer\",
\"Info\"
]
}]
}
],
\"ParticipationMoment\": \"2019-02-26 16:04:54\",
\"Completed\": true,
\"Profile\": \"147471\",
\"Test\": false
}" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/form/demodocform/interaction?source=API&way=testprofile&date=20%2F03%2F2019"
 
 
Response body
 
{
"interactionId": 2516
}

The response to this request will simply contain the auto-generated technical id of the interaction (that is to say, of the participation).

The participation will be thereby recorded. It can be reached through the ACTITO interface just as any standard form participation and enrichment rules will be applied.