Decipher Integration Guide

Ask Forsta to Allow Outbound Calls

Request Forsta/Decipher support to whitelist the ReDem API:

Please whitelist https://api.redem.io so that client-side JavaScript in my survey can POST to it.

If JavaScript is not allowed, use a server-side call with the same structure.

Create the ReDem Payload Container

Add a hidden question at the top of your XML (before <suspend/>):

<text label="ReDem_Payload" where="execute,survey" optional="0" size="25">
    <title>__INVISIBLE__</title>
    <row label="payload_json">{}</row>
    <row label="response_json">{}</row>
</text>

Add the initial window.reDem object:

<style name="survey.before" wrap="ready"><![CDATA[
    window.reDem = {
        respondentId : "${uuid}",
        surveyName   : "${survey.alt}",
        dataPoints   : [],
        activateCleaning : true,
        cleaningSettings  : {
            redemScore : 60,
            OES : { activate: true, score: 40, minDataPoints: 2 },
            CHS : { activate: true, score: 30 },
            GQS : { activate: true, score: 20, minDataPoints: 2 },
            TS  : { activate: true, score: 30 },
            BAS : { activate: true, score: 20, minDataPoints: 2 }
        },
        synchronousResponse : true
    };
]]></style>

Set Up BAS Tracking (Behavioral Analysis)

In order to use the BAS you must include a custom tracker based on this sample: Behavior Tracking. Since it requires customization, this is not available via CDN, so copy the code from that sample and adapt it to each open-end:

Replace QUESTION_ID with your Decipher label (D2, OE1, etc.)
Ensure textarea has consistent IDs or selectors for the tracker to bind properly.

The tracker logs KEYSTROKE and COPY_AND_PASTE events into sessionStorage.

Add Helper Function for Datapoints

Include the following helper once, preferably in survey.before:

<style name="survey.before" wrap="ready"><![CDATA[
    window.pushDataPoint = function(dp){
        window.reDem.dataPoints.push(dp);
        $("#question_ReDem_Payload .row[label='payload_json'] input").val(
        JSON.stringify(window.reDem)
        );
    };
]]></style>

Push Datapoints During Survey

Use below list for where and how to add datapoints:Quality Checks: OES
Where: question.after on open-ends
Sample:

pushDataPoint({
    qualityCheck:"OES",
    dataPointId:"D2",
    question:q.title,
    answer:document.querySelector('input,textarea').value,
    activateDuplicateDetection:true,
    allowedLanguages:["en","de"]
});

Quality Checks: BAS
Where: Same page as OES open-end
Sample:

pushDataPoint({
    qualityCheck:"BAS",
    dataPointId:"D2_BAS",
    interactionData:JSON.parse(sessionStorage.getItem("interaction_data"))
});

Quality Checks: TS
Where: After any page to measure time
Sample:

pushDataPoint({
    qualityCheck:"TS",
    dataPointId:"duration_D2",
    duration:Date.now()-pageStart
});

Quality Checks: GQS
Where: After grid matrix questions
Sample:

pushDataPoint({
    qualityCheck:"GQS",
    dataPointId:"gridQ1",
    gridAnswersPattern:[7,8,9,1,3,5,2,5,9,6]
});

Quality Checks: CHS
Where: Final page
Sample:

pushDataPoint({
    qualityCheck:"CHS",
    dataPointId:"CHS_Question",
    interviewData:[
        {questionId:"D2",question:"Where did…",answer:"…"}
    ]
});

Call ReDem API on the Final Page

Add a new page (e.g., ReDem_Screen) after the last <suspend/> with a “please wait…” message.In question.after, add:

<style name="question.after" wrap="ready"><![CDATA[
    fetch("https://api.redem.io/v2/addRespondent", {
        method: "POST",
        headers: {
        "api-key": "<YOUR_API_KEY>",
        "Content-Type": "application/json"
        },
        body: JSON.stringify(window.reDem)
    })
    .then(r => r.json())
    .then(json => {
        $("#question_ReDem_Payload .row[label='response_json'] input").val(JSON.stringify(json));
        if(json.results && json.results.respondentQuality.isExcluded){
        // handle exclusion logic
        } else {
        $("#btn_continue").click();
        }
    })
    .catch(e => {
        console.error(e);
        $("#btn_continue").click(); // fail open
    });
]]></style>

(Optional) Parse ReDem Scores into Export

Use the response_json row to extract and write additional scores to hidden questions:

{
    "results": {
        "respondentQuality": {
        "redemScore": 78,
        "isExcluded": false,
        "reasonsForExclusion": [],
        "dataPointsSummary": [],
        "qualityScoreSummary": []
        }
    }
}

Testing Checklist

Preview survey and provide multiple realistic answers.
Open DevTools → Network and confirm a 200 response from /v2/addRespondent.
Check that payload_json and response_json rows are populated.
Use sessionStorage.clear() on survey entry to reset BAS tracker data.

Quick Reference: Required Fields

Field	Type	Description
`respondentId`	string	e.g., `${uuid}`
`surveyName`	string	Human-readable name
`dataPoints`	array	Contains all datapoints
`activateCleaning`	boolean	Default: true
`cleaningSettings`	object	Score thresholds per module
`synchronousResponse`	boolean	Must be true in Decipher

Introduction

API Specifications

Endpoints

Advanced