Back to top

Decipher API

The Decipher REST API allows comprehensive automation of your private or shared Decipher instance.

New API Documentation Site is Live!

We're happy to announce that our Decipher API documentation has a new home! You will automatically be redirected to the FocusVision API docs site momentarily.

If you aren't redirected within 15 seconds, you can use the link below to go directly to our new API docs site.

https://docs.developer.focusvision.com/docs/decipher/api

Conventions

Introduction

The new Decipher API is RESTful. This means that an URL represents a certain resource or collection of resources:

  • a collection of surveys available to you – /api/v1/rh/companies/all/surveys

  • a specific survey – /api/v1/surveys/your/survey

  • a list of all users – /api/v1/rh/users

  • a specific user – /api/v1/rh/users/joe@yourcompany.com or /api/rh/users/4321

The convention is that accessing the “collection” URL gives you a list of resources, and appending the resource’s ID lets you read or write that particular resource.

A HTTP request to that resource will do something different depending on what HTTP method (verb) is used. This maps into the classical CRUD pattern: Create (POST), Read (GET), Update (POST), Delete (DELETE).

Accessing the API

All API requests must happen over HTTPS only, with a base URL of /api/v1/. For example, you might send a GET request to /api/v1/surveys/your/survey/data to get the data for your survey using the “Data Out” API.

In the distant future, we might upgrade the API to version 2. This will happen only if we need to make backwards incompatible changes. If at all possible, new parameters to existing functions will be added with default values. Old versions will be maintained for at least 3 years after being obsolete.

Language support:

The Python library includes a script called beacon that lets you easily call the API from the command line. The script will be more comfortable to use than a a tool like curl. Running beacon login will let you record your API key in a file and then let you run beacon get surveys/your/survey/datamap format=json to get a datamap.

Authentication and Authorization

To use the API, access the Research Hub and from the User Links menu select “API access”. Select “Create API key” to create a new key. You can have any amount of keys per account which makes sense if you use the security restrictions to assign different roles and security levels to the keys.

You may further restrict the usage of the API key to only certain calls, certain IP networks and also add an expiry date to the key. You may also want to create a user account specifically for API calls and grant that account access to a subset of your projects.

The generated key should be sent in any requests either a HTTP header named “x-apikey”.

GET /api/v1/hello
x-apikey: 3efrh03ejve1wuv3wv3tt8xxf0ur8g7fcy25j7nkx0cgr40tfph515e7k1c8kv4r

If you want to explore the API, the beacon script in the Python package above can be used to temporarily login to the system without requiring creation of an API key. See the documentation.

The API key is split into two parts: the first 32 characters are used to uniquely identify the key and never change once created. The last 32 characters are the secret (or password).

Error States

Following HTTP response codes are used:

  • 200 - success; your data is in the response body

  • 401 - invalid authentication; your API key is invalid, expired or not valid from this IP or action

  • 402 - payment required: you have exceeded your monthly API calls

  • 403 - invalid authorization: your API key is valid but you are not allowed access to this survey

  • 404 - not found: you asked for a survey or other resource that does not exist

  • 405 - method not allowed: you tried to e.g. DELETE something that does not support deletion

  • 429 - too many concurrent requests

  • 400 - other invalid parameter not covered above, e.g. survey cannot be loaded due to an error

A complete error response will look like this:

HTTP/1.0 401 invalid key. Verify the spelling of your key by accessing the Research Hub
Content-Length: 108
Content-Type: application/json

{
 "$error": "invalid key. Verify the spelling of your key by accessing the Research Hub",
 "$code": 401
}

The 201 Created response code (as recommended by some REST guides) is not currently used.

Accounting

Number of API calls and resources spent for each call are tracked. Currently we do not set a limit on amount of calls or resource usage for each call. Future releases may have restrictions of number of monthly calls, burst calls and number of simultaneous calls.

Every API response includes a header that shows number of API calls and resources used today: x-usage-today: 26 2481

You can view a monthly usage report from your Research Hub “User Links” page.

Content-types and RESTfulness

If your HTTP library can only use the POST method, pass instead a _method argument set to the real method you want.

The URL to send data to always starts with the path /api/v1/. Afterwards you select an resource type and possibly the resource ID. Each resource may then have an additional action to perform. Examples:

  • GET /api/v1/rh/companies/all/surveys – list all surveys (just as if you had accessed the Research Hub)

  • GET /api/v1/surveys/demo/bapi20/datamap – get this survey’s datamap

  • POST /api/v1/surveys/demo/bapi20/state/close – close this survey

  • GET /api/v1/rh/apikeys – list API keys for your company’s users

  • GET /api/v1/rh/apikeys/12435678 – get data for a specific API key

  • DELETE /api/v1/rh/apikeys/12435678 – disable that key

Not used REST features: caching, ETag, conditional requests (if-modified-since).

The Decipher API supports XML output, as defined by the IBM JSONX specification.

To retrieve an XML version of any resource, specify the header accept: application/xml. Example output:

<array xmlns="http://www.ibm.com/xmlns/prod/2009/jsonx">
  <object>
    <null name="restrictions"/>
    <number name="user_id">505</number>
    <number name="calls">0</number>
    <string name="user_fullname"></string>
    <string name="created_on">2014-09-23T18:10:43Z</string>
    <string name="key">eektgvwv8ynuuye9vfgfc36bah79v42r</string>
    <boolean name="active">true</boolean>
    <number name="resource">0</number>
    <string name="user_name">apitest</string>
    <null name="user_email"/>
  </object>
</array>

Throughout the document, JSON terminology is used for data types. Thus an object is a mapping of properties (which are always strings) to values (also known as “dict”, “dictionary”, “hash” or “map” in other languages):

{“property” : “some_value”, “other_property” : [1,2,3]}

An array is a sequence of elements:

[element0, element1, element2]

Each value in an array or object can be null, an object, an array, a string (which may contain any unicode character), a number (all numbers are floating points) or a boolean constant (true or false).

Dates

Date times use ISO 8601 standard.

Example format:

  • 2014-01-10T20:08:08Z – 2014, January, 10th, time is 20:08:08 and the time zone is GMT as Z alone was specified

Security

A preferred option is to create a new user account for API usage with restricted access rather than user your own account that will have full access. You don’t have to login to that user but can create an API key for them from your API access page.

You can also create any amount of restricted API keys. Restrictions can allow:

  • only certain API calls to be used (i.e. you may only access the user list)

  • only certain methods to those calls to be used (i.e. you may only list users, but not create new ones)

  • force parameters (i.e. you can use the datamap API but only for survey X, Y, Z)

A restriction configuration is an optional Javascript object. If it is {}, there are no restrictions. Otherwise it may contain the following values:

  • networks: limit access to only these IP addresses or networks. Specify an array such as ["1.2.3.4"] or ["5.6.7.0/24", "3.4.5.3"]. Each item must be an IP (v4) address only or a proper network (i.e. 5.6.7.0/24 is allowed but 5.6.7.1/24 is not: the network bits must be cleared).

We had an old “data API” that used basic authentication. That old API will eventually be deprecated.

Additional features

Every API supports simple projection to let you select a subset of data. Pass in select as an argument set to a comma-separated list of properties to return, e.g. select=id,login,active to view only those 3 fields when calling rh/users.

APIs that return an array of objects can return data in Excel 2007 format instead of JSON. Pass in contentType set to excel. Pass in e.g. top=5 to return only he first 5 objects of an array.

Impersonation

An API key belonging to a staff or supervisor user can change its identity to any other user for the duration fo the API call. This is useful when acting on behalf of that user without having to create separate API keys for each user. To perform impersonation, send the x-impersonate header containing the email address or numeric user ID. You must be able to manage this user in the portal to impersonate them. Additional information about this is logged in the audit log of the impersonator and the subject.

Data input and output

Download or upload participant data.

Data

Download data
GET/api/v1/surveys/{survey}/data

Run a report and retrieving matching participants. Supported data formats:

  • tab simple tab-delimited format, with a leading row with column headings

  • fwu fixed-width format with data starting at certain offsets based on unicode characters

  • fw fixed-width format with data starting at certain offsets based on raw bytes (beware, use in legacy programs only)

  • flat flattened format containing OE data (the flatShowEmpty, default 1, survey attribute determines whether blank values are shown)

  • flat_all flattened format containing non-blank data for all fields, not just OE

  • pipe like tab, but delimited by the pipe character, i.e. uuid|date|q1

  • csv like tab, but delimited by the comma character. Items with a comma in them are “quoted,like,this”

  • cb IBM column binary

  • json JSON. An array with one element per participant. Each element is an object mapping variable label to value for non-blank values only.

  • spss SPSS default format (SPSS 15)

  • spss16 *.sav Files for SPSS 16+ with Unicode Support (zipped)

  • spss15 SPSS 15 *.sav Files (zipped)

  • spss16_oe SPSS 16+ *.sav Files including All Open End Data (zipped)

  • spss_data Fixed-Width Data Files and SPSS Script File (zipped)

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/data
URI Parameters
HideShow
survey
string (required) 

path to survey to run data for. You must have data view permissions.

format
string (optional) Default: tab 

one of the supported data formats

layout
int (optional) Default: null 

layout ID, either hardcoded or retrieved using Layouts API

fields
array (optional) 

an array of field names to retrieve.

  • If using a GET request encode the array as a comma-separated list

  • If using a POST request, it must be a JSON array

start
datetime (optional) Example: 2011-12-14T17:50Z

start time using ISO 8601 format. E.g. “2011-12-14T17:50Z” for GMT time corresponding to 14th December, 2011, 17:50 GMT. This is optional: if you do not specify this parameter, you will get data starting at the earliest possible record.

end
datetime (optional) 

maximum completion date of participants to include. Like start, this is optional

cond
string (optional) Default: All 

condition required to retrieve the participant. This is a Python condition as if you would enter in survey logic or crosstabs. For example, “qualified and q3.r2” retrieves only participants that were qualified and answered q3 as r2.

stacking
string (optional) 

argument to specify stacked data file. Options are top which outputs all the non-looped variables and label which outputs the looped data for the specific loop label.

Request  /api/v1/surveys/demo/survey/data?format=csv&fields=uuid,date&cond=q1.r1
Response  200
HideShow
Headers
Content-Type: text/plain
Body
6e1kpqns68q3ue9k,12/19/2013 17:55

Download data
POST/api/v1/surveys/{survey}/data

This is equivalent to the GET request. However GET request are limited to around 1000-character URLs. We include a POST version that does not generate data but allows for any amount of fields to be specified

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/data
URI Parameters
HideShow
survey
string (required) 

path to survey to run data for. You must have data view permissions.

format
string (optional) Default: tab 

one of the supported data formats

layout
int (optional) Default: null 

layout ID, either hardcoded or retrieved using Layouts API

fields
array (optional) 

an array of field names to retrieve.

  • If using a GET request encode the array as a comma-separated list

  • If using a POST request, it must be a JSON array

start
datetime (optional) Example: 2011-12-14T17:50Z

start time using ISO 8601 format. E.g. “2011-12-14T17:50Z” for GMT time corresponding to 14th December, 2011, 17:50 GMT. This is optional: if you do not specify this parameter, you will get data starting at the earliest possible record.

end
datetime (optional) 

maximum completion date of participants to include. Like start, this is optional

cond
string (optional) Default: All 

condition required to retrieve the participant. This is a Python condition as if you would enter in survey logic or crosstabs. For example, “qualified and q3.r2” retrieves only participants that were qualified and answered q3 as r2.

stacking
string (optional) 

argument to specify stacked data file. Options are top which outputs all the non-looped variables and label which outputs the looped data for the specific loop label.

Datamap

Following formats are supported for datamaps. Most correspond to a datamap you can download from crosstabs.

  • json a machine-readable format describing all questions and variables and their relations.

  • html HTML

  • text Plain text

  • tab Similar to plain text but with tabs

  • xlsx Similar to plain text but in excel xlsx format

  • fw-html, fw-tab, fw-text As the 3 above, but with fixed-width start/end annotations

  • cb-html, cb-tab, cb-text As the 3 above, but containing column binary card offsets

  • uncle – this and below options added in Decipher 28.

  • wincross – note that wincross does not support “layout”

  • sss - Triple-S 1.5 XML

  • sas

  • quantum

  • spss_fw – an SPSS script where data is described by fixed-width data file start,end ranges

  • spss_tab – an SPSS script using tab column names

  • netmr-tab, netmr-csv – Net MR datamap in tab-delimited or CSV versions

Retrieve Datamap
GET/api/v1/surveys/{survey}/datamap

Retrieve the datamap of a survey, explaining questions and variables.

Example URI

GET release.decipherinc.com/api/v1/surveys/selfserve/1234/456/datamap
URI Parameters
HideShow
survey
string (required) Example: selfserve/1234/456

Path to the survey.

format
string (required) 

One of the supported formats

layout
int (optional) Default: null 

layout ID, either hardcoded or retrieved using Layouts API

qa
bool (optional) Default: false 

Include QA codes (applies only to the html variants)

Request
HideShow
Body
GET /api/v1/surveys/demo/api/datamap?format=json&qa=1
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "variables": [
      {
   "vgroup": "q2",
   "title": "Col c3 - q2",
   "type": "single",
   "qtitle": "q2",
   "rowTitle": null,
   "label": "q2c3",
   "qlabel": "q2",
   "colTitle": "Col c3",
   "col": "c3",
   "row": null
  }, ...
  "questions": [
   {
   "qtitle": "q2",

   "variables": [
    {
     "vgroup": "q2",
     "title": "Col c1 - q2",
     "type": "single",
     "qtitle": "q2",
     "rowTitle": null,
     "label": "q2c1",
     "qlabel": "q2",
     "colTitle": "Col c1",
     "col": "c1",
     "row": null
    }, ...
    ],

   "values": [
    {
     "value": 1,
     "title": "Row r1"
    },
    {
     "value": 2,
     "title": "Row r2"
    },
    {
     "value": 3,
     "title": "Row r3"
    }
   ],
   "grouping": "cols",
   "type": "single",
   "qlabel": "q2"
  },

Data Layouts

Allows layouts created in Data Layout Manager to be enumerated. A Data Layout will have the below properties:

  • createdBy: (string) email address of creator

  • createdOn: (datetime) time layout was created

  • description: (string) human readable description of layout

  • id: (int) unique id of layout

  • updatedBy: (string) email address of user who last modified the layout

  • updatedOn: (datetime) time layout was last updated

  • variables: (array) array of data variables

    • altlabel: (string) optional alternative label for variable
    • fwidth: (int) number of characters the variable will occupy in fixed width data formats
    • label: (string) unique label of variable
    • minStart: (int) optional offset the variable should start at
    • new: (boolean) did the variable not exist in the previous datamap
    • qlabel: (string) label of variable’s parent question
    • qtype (string) question type of the underlying question (corresponds to the lower-case XML tag, e.g. “radio”)
    • shown: (boolean) is the variable shown in this layout
    • src: (string) source of variable
      • g for system generated (i.e. virtual)
      • s for survey
      • y for system (uuid, date, start_date, any extraVariable (including record, ipAddress, userAgent))
    • title: (string) textual representation of variable

Retrieve Data Layouts
GET/api/v1/surveys/{survey}/layouts

Returns a list of Data Layouts for a survey.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/layouts
URI Parameters
HideShow
survey
string (required) 

path of survey to retrieve Data Layouts for. You must have report view permissions.

Data Feed

Get data from multiple live surveys using a single API endpoint (optionally restrict by date and survey paths). A paginated response (10,000 records at a time) with data will be received; once it’s explicitly acknowledged by another API call, next call will receive new data since last call. Decipher 28. You can fetch data for qualified participants or all participants; you can fetch all answers or just e.g. UUID, source and status. You create any amount of simultaneous feeds and can also get data only for a subset of surveys rather than all available to your user.

Get new data
GET/api/v1/datafeed/{feed}

Every live or closed survey accessible to this account will be considered for the feed. This list can be filtered by the paths argument. Once a complete list of surveys has been generated, participants with data update time greater than the last time the feed was ran are retrieved. If start is supplied, then the participant is further filtered.

By default cond is set to qualified retrieving only qualified participants. You can specify ALL for all participants including partials or other conditions known, to Crosstabs. Invalid conditions will be returned as errors but will not prevent other surveys’ data from being generated.

Pagination: This call will return 10,000 participants at a time. If more would be generated, complete will be set to false in the returned record and you should call this function again to get more data. A complete feed means that at the time of each survey being processed, no more data was available.

Data format: The data returned uses the JSON data format, using the default variable layout.

Acknowledgement: If you set autoAck to true, the data is automatically advanced. If not, every time you receive data and after you successfully process it you must make the /ack call as documented below with the ack value you received. Otherwise the feed is not advanced and you will receive the data again. Note there is no guarantee that you receive exactly the same response as in the last call as new surveys or participants may have appeared. However the data you were sent is guaranteed to be sent again.

When to use ACK: If you do not use the ACK system, Decipher advances the feed state as soon as the entire request was completed – even if the network connection is reset before you have received the entire reply, or if an error is generated while you are processing the data. We only recommend autoAck for testing purposes.

Partial data: If you supply ALL as cond rather than the default qualified then partial data is also included. The same participant record may appear multiple times: once each time his partial data is updated and once if they complete.

Data edits: a data edit that modifies participant data does NOT resend the data.

New surveys: The list of surveys to include in the feed is considered on every request. As new surveys go live or are closed they will be added to the feed. Set paths to a specific subset of the surveys you want if you want consider only those. This will filter the list of live and closed surveys to include only those specified. This must be repeated for every request.

You must explicitly acknowledge this data by calling the ack method below and passing in the ack value received here. Otherwise the next GET will again send the same data.

The response is an object containing these fields:

  • complete: if true, this response is all the data available. If false, more data exists and you should continue to ask for the data feed to get more data immediately. By default, no more than 10,000 records will be sent at a time.

  • ack: this UUID describes this particular response value; the feed will move forward only if the caller acknowledges receipt in the next call (see below).

  • results: an array of participant records. Each participant record contains:

    • variables from the default layout as per JSON data record
    • $survey set to the path of the survey

Example URI

GET release.decipherinc.com/api/v1/datafeed/feed
URI Parameters
HideShow
feed
string (required) 

any unique ID that will identify the feed. Feeds are namespaced per user, so your all feed is unique to you.

start
datetime (required) 

ISO-8601 date with the minimum completion time to retrieve. Record before this date will not be considered. This parameter should be passed with the same value every time until data has been exhausted. Thus it should only be used if somehow data received is lost and needs to be re-synchronized.

format
string (required) Default: json 

Normally not used. Use json_panel as value to synchronize data with a participant panel (this feature is enabled only for certain clients)

autoAck
boolean (optional) Default: false 

if set to true, no ack call is required to move the feed forward

states
array (required) Default: ["live", "closed"] 

list of survey states to accept data from. By default only live and closed surveys are scanned for data but through this parameter you may include surveys in dev or testing mode

paths
array (required) 

rather than retrieving all the surveys visible to you, retrieve only data from these surveys. This is useful for testing.

fields
array (optional) Example: ["uuid", "status"]

extract only these variables from all the surveys.

cond
string (optional) Default: qualified 

by default only qualified participants are fetched. Specify ALL for all data or another condition (which must be applicable to ALL your surveys)

limit
int (optional) Default: 10000 

Limit the number of results returned per request.

surveyLabels
bool (optional) Default: false 

If survey labels should be part of the request.

Reset feed
DELETE/api/v1/datafeed/{feed}

Clears the state of the feed. Next GET will receive data from the beginning.

Example URI

DELETE release.decipherinc.com/api/v1/datafeed/feed
URI Parameters
HideShow
feed
string (required) 

any unique ID that will identify the feed. Feeds are namespaced per user, so your all feed is unique to you.

Update feed
PUT/api/v1/datafeed/{feed}

Updates the internal feed state. Call the Feed state GET method below to get the current state. You can then e.g. copy it over to another name.

Example URI

PUT release.decipherinc.com/api/v1/datafeed/feed
URI Parameters
HideShow
feed
string (required) 

any unique ID that will identify the feed. Feeds are namespaced per user, so your all feed is unique to you.

state
object (required) 

state previously retrieved using datafeed/{feed}/state

Data Feed: State

Get feed state
GET/api/v1/datafeed/{feed}/state

Returns the stored internal state for this feed. This is mainly for troubleshooting processes. An object with a single key, state, its value an object mapping survey path to a list of two items:

  • 0: minimum timestamp for data retrieval

  • 1: an array of UUIDs of records retrieved

The list of UUIDs is only set if data was partially retrieved during a POST due of exceeding the 10,000 element limit. Once a survey’s data has been completely returned up until a timestamp, this list is cleared.

Example URI

GET release.decipherinc.com/api/v1/datafeed/feed/state
URI Parameters
HideShow
feed
string (required) 

any unique ID that will identify the feed. Feeds are namespaced per user, so your all feed is unique to you.

Data Feed: acknowledgement

Acknowledge
POST/api/v1/datafeed/{feed}/ack

Call this method to move the data feed forward.

Example URI

POST release.decipherinc.com/api/v1/datafeed/feed/ack
URI Parameters
HideShow
feed
string (required) 

any unique ID that will identify the feed. Feeds are namespaced per user, so your all feed is unique to you.

ack
string (required) 

the ack value you received from calling GET

Response Summary - Completions

Get Completions
GET/api/v1/surveys/{survey}/summary/completions

Returns the equivalent of the “Completions” tab in the Response Summary report (formerly known as field report).

Return object:

  • segments: list of segment names, e.g. “Total”, “Participant source (list=1)” similar to column names when splitting

  • rows: list with one object per a row that would be displayed in the Completions tab containing:

    • formula: the formula used to compute the value. This should be used to search for specific values
    • name: the name as displayed in the response summary to the user. This may contain HTML formatting and be in the user’s language
    • title: additional description of the row
    • cells: one object for each segment the response summary is split by containing:
      • raw: the raw numeric value (e.g. 0.76 or 240)
      • formatted: the formatted value (e.g. 76% for percentages or 04:00 for completion time)
      • title: the formula used to compute the raw value with numbers replacing the variable names
      • vsplit: the split identifier. This can be passed to the variables down URL (/rep/{survey}:vars?only=VSPLIT) and this is what the “Clickthrough” cell links to in the response summary user interface

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/summary/completions
URI Parameters
HideShow
survey
string (required) 

The survey to run the report for. You must have dashboard.view permission for the project.

split
string (optional) Example: list

If supplied, create segments for this split which is e.g. “list”.

Response  200
HideShow
Body
{
  "segments": [
    "Total"
  ],
  "rows": [
    {
      "formula": "clickthrough",
      "cells": [
        {
          "vsplit": "",
          "raw": 100,
          "formatted": 100,
          "title": ""
        }
      ],
      "name": "Click Through",
      "title": "participants who opened the first page of the survey"
    },
    {
      "formula": "partial",
      "cells": [
        {
          "vsplit": "",
          "raw": 27,
          "formatted": 27,
          "title": ""
        }
      ],
      "name": "<span class=\"pl-5\">Partial Completes</span>",
      "title": "participants who dropped out of the survey"
    },
    {
      "formula": "terminates",
      "cells": [
        {
          "vsplit": "",
          "raw": 26,
          "formatted": 26,
          "title": ""
        }
      ],
      "name": "<span class=\"pl-5\">Terminates</span>",
      "title": "participants who were terminated"
    },
    {
      "formula": "overquota",
      "cells": [
        {
          "vsplit": "",
          "raw": 16,
          "formatted": 16,
          "title": ""
        }
      ],
      "name": "<span class=\"pl-5\">Overquota</span>",
      "title": "participants terminated due to quota logic"
    },
    {
      "formula": "qualified",
      "cells": [
        {
          "vsplit": "",
          "raw": 31,
          "formatted": 31,
          "title": ""
        }
      ],
      "name": "Qualified Completes",
      "title": "participants who qualified and completed the survey"
    },
    {
      "formula": "(terminates + overquota + qualified) / clickthrough",
      "cells": [
        {
          "vsplit": "",
          "raw": 0.73,
          "formatted": "73%",
          "title": "(26 + 16 + 31) / 100"
        }
      ],
      "name": "Participation Rate",
      "title": "(Terminates + Overquota + Qualified) / Click-Through"
    },
    {
      "formula": "(qualified + overquota) / (clickthrough - partial - excluded)",
      "cells": [
        {
          "vsplit": "",
          "raw": 0.8103448275862069,
          "formatted": "81%",
          "title": "(31 + 16) / (100 - 27 - 15)"
        }
      ],
      "name": "Incidence",
      "title": "(Qualified + Overquota) / (Click-Through - Partial - Excluded)"
    },
    {
      "formula": "completionTime",
      "cells": [
        {
          "vsplit": "",
          "raw": null,
          "formatted": "0:30",
          "title": ""
        }
      ],
      "name": "Completion Time (average)",
      "title": "Average completion time for a qualified participant"
    },
    {
      "formula": "completionTimeMedian",
      "cells": [
        {
          "vsplit": "",
          "raw": 29,
          "formatted": "0:29",
          "title": ""
        }
      ],
      "name": "Completion Time (median)",
      "title": "Median completion time for a qualified participant"
    }
  ]
}

Response Summary - Campaigns

Get Campaigns
GET/api/v1/surveys/{survey}/summary/campaigns

Returns the equivalent of the “Campaigns” tab in the Response Summary report (formerly known as field report).

Return object:

  • segments: list of segment names, e.g. “Total”, “Participant source (list=1)” similar to column names when splitting

  • rows: list with one object per a row that would be displayed in the Campaigns tab containing:

    • formula: the formula used to compute the value. This should be used to search for specific values
    • name: the name as displayed in the response summary to the user. This may contain HTML formatting and be in the user’s language
    • title: additional description of the row
    • cells: one object for each segment the response summary is split by containing:
      • raw: the raw numeric value (e.g. 0.76 or 240)
      • formatted: the formatted value (e.g. 76% for percentages or 04:00 for completion time)
      • title: the formula used to compute the raw value with numbers replacing the variable names
      • vsplit: the split identifier.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/summary/campaigns
URI Parameters
HideShow
survey
string (required) 

The survey to run the report for. You must have dashboard.view permission for the project.

split
string (optional) Example: list

If supplied, create segments for this split which is e.g. “list”.

Response  200
HideShow
Body
{
  "segments": [
    "Total"
  ],
  "rows": [
    {
      "formula": "total",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 54000,
          "formatted": 54000,
          "title": ""
        }
      ],
      "name": "List Total",
      "title": "Total amount of email addresses in all lists"
    },
    {
      "formula": "sent",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 54000,
          "formatted": 54000,
          "title": ""
        }
      ],
      "name": "Sent",
      "title": "Number of emails attempted sent"
    },
    {
      "formula": "malformed",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 2230,
          "formatted": 2230,
          "title": ""
        }
      ],
      "name": "- Bad/Malformed",
      "title": "Incorrectly formatted email addresses"
    },
    {
      "formula": "dupe",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 2309,
          "formatted": 2309,
          "title": ""
        }
      ],
      "name": "- Duplicate Addresses",
      "title": "Decipher automatically dedupes lists so the recipient will only receive one email"
    },
    {
      "formula": "optout",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 6653,
          "formatted": "6653 (0)",
          "title": ""
        }
      ],
      "name": "- Opt-Outs",
      "title": "Decipher will not send emails to people who have opted out"
    },
    {
      "formula": "throttleClient + throttleSurvey",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 4479,
          "formatted": 4479,
          "title": "2238 + 2241"
        }
      ],
      "name": "- Throttled Addresses",
      "title": "Recently contacted addresses not included in this send"
    },
    {
      "formula": "bounce",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 2224,
          "formatted": 2224,
          "title": ""
        }
      ],
      "name": "- Bounce-Backs *",
      "title": "Email returned from server (address no longer exists)"
    },
    {
      "formula": "additional",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 4536,
          "formatted": 4536,
          "title": ""
        }
      ],
      "name": "- Additional Suppression",
      "title": "Emails not sent for other reasons"
    },
    {
      "formula": "potential",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 29373,
          "formatted": 29373,
          "title": ""
        }
      ],
      "name": "Potential Contacts *",
      "title": "Actual, potential number of contacts"
    },
    {
      "formula": "opened",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 13700,
          "formatted": 13700,
          "title": ""
        }
      ],
      "name": "Opened **",
      "title": "Measured number of opened invitations"
    },
    {
      "formula": "opened / potential",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 0.4664147346202295,
          "formatted": "47%",
          "title": "13700 / 29373"
        }
      ],
      "name": "Open Rate **",
      "title": "Opened / Potential"
    },
    {
      "formula": "clickthrough / potential",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 0.34044871140162736,
          "formatted": "34%",
          "title": "10000 / 29373"
        }
      ],
      "name": "Click-Through Rate",
      "title": "Click-Through/ Potential"
    },
    {
      "formula": "(terminates + overquota + qualified) / potential",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 0.2256494059169986,
          "formatted": "23%",
          "title": "(0 + 0 + 6628) / 29373"
        }
      ],
      "name": "Response Rate *",
      "title": "(Terminates + Overquota + Qualified) / Potential"
    },
    {
      "formula": "spam / spam_base",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 0,
          "formatted": 0,
          "title": "0 / 18601"
        }
      ],
      "name": "Spam Rate",
      "title": "Complaints Received / Emails with Feedback Loop"
    },
    {
      "formula": "unsent",
      "cells": [
        {
          "vsplit": "Total",
          "raw": 2196,
          "formatted": 2196,
          "title": ""
        }
      ],
      "name": "Unsent",
      "title": "Emails remaining to be sent"
    }
  ],
  "reminders": {
    "total_sent": [
      {
        "vsplit": "Total",
        "value": 250
      }
    ],
    "rows": [
      {
        "cells": [
          {
            "vsplit": "Total",
            "value": 200
          }
        ],
        "name": "04/22/2020 22:10 (1)"
      },
      {
        "cells": [
          {
            "vsplit": "Total",
            "value": 50
          }
        ],
        "name": "04/22/2020 23:20 (2)"
      }
    ]
  },
  "initial_sends": [
    {
      "rows": [
        {
          "formula": "total",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 1000,
              "formatted": 1000,
              "title": ""
            }
          ],
          "name": "List Total",
          "title": "Total amount of email addresses in this send"
        },
        {
          "formula": "malformed",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 47,
              "formatted": 47,
              "title": ""
            }
          ],
          "name": "- Bad/Malformed",
          "title": "Incorrectly formatted email addresses"
        },
        {
          "formula": "dupe",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 48,
              "formatted": 48,
              "title": ""
            }
          ],
          "name": "- Duplicate Addresses",
          "title": "Decipher automatically dedupes lists so the recipient will only receive one email"
        },
        {
          "formula": "optout",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 135,
              "formatted": "135 (0)",
              "title": ""
            }
          ],
          "name": "- Opt-Outs",
          "title": "Decipher will not send emails to people who have opted out"
        },
        {
          "formula": "throttleClient + throttleSurvey",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 79,
              "formatted": 79,
              "title": "38 + 41"
            }
          ],
          "name": "- Throttled Addresses",
          "title": "Recently contacted addresses not included in this send"
        },
        {
          "formula": "bounce",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 42,
              "formatted": 42,
              "title": ""
            }
          ],
          "name": "- Bounce-Backs *",
          "title": "Email returned from server (address no longer exists)"
        },
        {
          "formula": "additional",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 88,
              "formatted": 88,
              "title": ""
            }
          ],
          "name": "- Additional Suppression",
          "title": "Emails not sent for other reasons"
        },
        {
          "formula": "potential",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 523,
              "formatted": 523,
              "title": ""
            }
          ],
          "name": "Potential Contacts *",
          "title": "Actual, potential number of contacts"
        }
      ],
      "name": "04/22/2020 19:20",
      "historical": false
    },
    {
      "rows": [
        {
          "formula": "total",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 3000,
              "formatted": 3000,
              "title": ""
            }
          ],
          "name": "List Total",
          "title": "Total amount of email addresses in this send"
        },
        {
          "formula": "malformed",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 140,
              "formatted": 140,
              "title": ""
            }
          ],
          "name": "- Bad/Malformed",
          "title": "Incorrectly formatted email addresses"
        },
        {
          "formula": "dupe",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 120,
              "formatted": 120,
              "title": ""
            }
          ],
          "name": "- Duplicate Addresses",
          "title": "Decipher automatically dedupes lists so the recipient will only receive one email"
        },
        {
          "formula": "optout",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 375,
              "formatted": "375 (0)",
              "title": ""
            }
          ],
          "name": "- Opt-Outs",
          "title": "Decipher will not send emails to people who have opted out"
        },
        {
          "formula": "throttleClient + throttleSurvey",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 254,
              "formatted": 254,
              "title": "128 + 126"
            }
          ],
          "name": "- Throttled Addresses",
          "title": "Recently contacted addresses not included in this send"
        },
        {
          "formula": "bounce",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 151,
              "formatted": 151,
              "title": ""
            }
          ],
          "name": "- Bounce-Backs *",
          "title": "Email returned from server (address no longer exists)"
        },
        {
          "formula": "additional",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 260,
              "formatted": 260,
              "title": ""
            }
          ],
          "name": "- Additional Suppression",
          "title": "Emails not sent for other reasons"
        },
        {
          "formula": "potential",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 1591,
              "formatted": 1591,
              "title": ""
            }
          ],
          "name": "Potential Contacts *",
          "title": "Actual, potential number of contacts"
        }
      ],
      "name": "04/22/2020 20:22",
      "historical": false
    },
    {
      "rows": [
        {
          "formula": "total",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 50000,
              "formatted": 50000,
              "title": ""
            }
          ],
          "name": "List Total",
          "title": "Total amount of email addresses in this send"
        },
        {
          "formula": "malformed",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 2043,
              "formatted": 2043,
              "title": ""
            }
          ],
          "name": "- Bad/Malformed",
          "title": "Incorrectly formatted email addresses"
        },
        {
          "formula": "dupe",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 2141,
              "formatted": 2141,
              "title": ""
            }
          ],
          "name": "- Duplicate Addresses",
          "title": "Decipher automatically dedupes lists so the recipient will only receive one email"
        },
        {
          "formula": "optout",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 6143,
              "formatted": "6143 (0)",
              "title": ""
            }
          ],
          "name": "- Opt-Outs",
          "title": "Decipher will not send emails to people who have opted out"
        },
        {
          "formula": "throttleClient + throttleSurvey",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 4146,
              "formatted": 4146,
              "title": "2072 + 2074"
            }
          ],
          "name": "- Throttled Addresses",
          "title": "Recently contacted addresses not included in this send"
        },
        {
          "formula": "bounce",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 2031,
              "formatted": 2031,
              "title": ""
            }
          ],
          "name": "- Bounce-Backs *",
          "title": "Email returned from server (address no longer exists)"
        },
        {
          "formula": "additional",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 4188,
              "formatted": 4188,
              "title": ""
            }
          ],
          "name": "- Additional Suppression",
          "title": "Emails not sent for other reasons"
        },
        {
          "formula": "potential",
          "cells": [
            {
              "vsplit": "Total",
              "raw": 27259,
              "formatted": 27259,
              "title": ""
            }
          ],
          "name": "Potential Contacts *",
          "title": "Actual, potential number of contacts"
        }
      ],
      "name": "04/22/2020 20:28",
      "historical": false
    }
  ]
}

Response Summary - Available Splits

Get Splits
GET/api/v1/surveys/{survey}/summary/splits

Returns the split names you can split the response summary report by. These are typically extraVariables that have a fixed set of values (e.g. list, decLang).

Return object is a list of objects containing:

  • name: this symbolic name can be passed as split into the other response summary APIs

  • description: additional description

  • segments: list of segments within this split, each an object containing:

    • description: English description of the split
    • values: internal object describing the logic behind the split

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/summary/splits
URI Parameters
HideShow
survey
string (required) 

The survey to run the report for. You must have dashboard.view permission for the project.

campaigns
boolean (optional) 

Include campaign specific splits.

Modify Data

Allows for modification of the participant data. Depending on verb selected you are either deleting/disqualifying participants, modifying data of an existing participant or creating completely new participant records. This is similar to the actions possible through the “Edit Data” system as seen in View/Edit Responses report

Support for this was added in Decipher 28.

Return object:

  • stats (object): overall statistics of what happened with your data edit requested:
    • created (int): number of new records created
    • deleted (int): number of records deleted
    • disqualified (int): number of qualified records disqualified or deleted
    • unseen (int): number of rows that did not match existing records when not creating new records
    • rewritten (int): records where data was modified
    • unchanged (int): records where your updated data did not cause changes
    • inrows (int): total amount of records processed (rewritten + unchanged + deleted + created)
    • fieldsIdentical (int): data update requests not done because existing data was identical. This counts individual cells
    • fieldsUpdated (int): data fields updated by the request
    • fieldsErronous (int): data supplied that was not valid
    • fieldsIgnored (int): cells ignored because uploading into legacy weight/record values (this is for surveys older than 2005)
    • fieldsProcessed (int): total fields processed
    • bad (array): invalid values detected during edit/update
    • rows (int): number of fields in your input data
    • unmatchedDeletions (int): records that you asked to be deleted but did not match existing records
  • backup (string): where is the previous version of the data? This can be restored by support or a shell user on a Beacon Cloud installation

Additional error codes:

  • 400 invalid key: the key supplied is not a valid variable

  • 400 bad variable <name>: some of the variables supplied in data do not exist or cannot be updated.

Performance notes: The Decipher data files are geared towards analysis rather than editing and updates. During the data editing process, participants will be prevented from completing the survey. The time to complete a data edit will vary with amount of participants in the data file and number of variables but a typical speed is 1,000 records / 25,000 cells per second.

After a data edit, many “cache entries” are cleared such as virtual data. If your report has a complex virtual question, the next report run might take extra time to complete.

Partial data: Note that while you can modify partial participant data, if the participant returns and submits more data which is recovered or completes, the changes will be overwritten. Deleting a partial participant will stop further automatic recovery, but will not prevent the participant from completing again.

Errors: An upload of a row with data that is not correct will not stop the correct data from being applied. E.g. you if you modify q1 to a valid value 2, and q2 to an invalid value 5 the application of q1 will still happen. If it’s critical to avoid this, start by modifying the data in a test mode first and check that fieldsErronous is 0.

Data: Each data record may include different variables. Thus it is possible to change only variable q1 for one record and only change q2 for another record. Any virtual variables included in the data will be ignored.

Special fields: The date field must be supplied in the server’s time format and time zone. On all but 1 of Decipher servers, the time format is %m/%d/%Y %H:%M i.e. Month, Day, Year (4 digit), then 24-hour and minute. Note that this means while seconds are stored in the data file, they can only be imported as 0.

Logging: Changes through this API are logged, but do not trigger the data edit notification email.

Memory usage: Importing a 50 megabyte file containing 1 million records each with 4 fields requires 1500 MB memory. The overhead comes mostly from number of cells in the data array imported at once.

Edit Existing Data
PUT/api/v1/surveys/{survey}/data/edit

Modify data of existing participants in the survey. As data, supply objects containing the data you want to update. As with all variants, you must supply a key to match by and supply that key for each record.

Elements in data that do not match an existing record are discarded.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/data/edit
URI Parameters
HideShow
survey
string (required) 

The survey to edit data in. You must have data edit permission for the project.

key
string (required) Example: uuid

The field used to match your participant data. This should be a unique variable. Supplying a non-unique key will change every matching record. This is implicitly null when creating new records.

data
array (required) 

An array of the participant records. Each element of the array is an object with the key being the column name matching a variable name, and the value the value you want to update. You can specify any amount of variables.

test
boolean (optional) Default: false 

Do not execute the edit, but return the changes that would be applied at the time of the call.

layout
int (optional) 

The id of a custom data layout. A custom export layout can relabel fields. If you exported some data with fields that have been relabelled in a layout and now are importing it back, you should use the same layout.

allVariables
bool (optional) Default: false 

Allow editing of notdp variables

Request
HideShow

In the example request below, the key is set to source: we supply a source in each element of the array and attempt to update q1 (a text question) and q2 (an ordinal question but only with values 1-4 allowed). In the return value, bad contains the values that were not correct with index (0-based) into the data, the column label, the value attempted set and a human-readable error message. inrows is set to 5, so the existing data file has 5 responses: of those 2 were rewritten with new data and 3 were left unchanged. fieldsIdentical is set to 2, so some of the data attempted uploaded was already in place.

Body
{
  "data": [
    {
      "q1": "Bob Bobson",
      "source": "3",
      "q2": "1"
    },
    {
      "q1": "Joe Q. Joeson",
      "source": "4",
      "q2": "42"
    }
  ],
  "key": "source"
}
Response  200
HideShow
Body
{
  "stats": {
    "fieldsIgnored": 0,
    "rows": 2,
    "fieldsErronous": 1,
    "rewritten": 2,
    "created": 0,
    "deleted": 0,
    "disqualified": 0,
    "unchanged": 3,
    "updated": 0,
    "bad": [
      [
        1,
        "q2",
        42,
        "Invalid value (allowable values are 1-4)"
      ]
    ],
    "fieldsUpdated": 3,
    "unseen": 0,
    "fieldsIdentical": 2,
    "inrows": 5,
    "unmatchedDeletions": 0,
    "fieldsProcessed": 6
  },
  "backup": "selfserve/1234/dataedit/data/old-results/011.results.*"
}

Create new data
POST/api/v1/surveys/{survey}/data/edit

Create new records in the survey. All records specified are always created anew (if you suspect some exist in the survey already, you should fetch and filter before sending new data). Validation of data works exactly as with the PUT variant.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/data/edit
URI Parameters
HideShow
survey
string (required) 

The survey to edit data in. You must have data edit permission for the project.

key
string (required) Example: uuid

The field used to match your participant data. This should be a unique variable. Supplying a non-unique key will change every matching record. This is implicitly null when creating new records.

data
array (required) 

An array of the participant records. Each element of the array is an object with the key being the column name matching a variable name, and the value the value you want to update. You can specify any amount of variables.

test
boolean (optional) Default: false 

Do not execute the edit, but return the changes that would be applied at the time of the call.

layout
int (optional) 

The id of a custom data layout. A custom export layout can relabel fields. If you exported some data with fields that have been relabelled in a layout and now are importing it back, you should use the same layout.

allVariables
bool (optional) Default: false 

Allow editing of notdp variables

Delete data
DELETE/api/v1/surveys/{survey}/data/edit

Disqualify or delete the records. You must set mode to “delete” to delete data. We recommend disqualifying rather than deleting, as deleted records can only be restored by support or a shell user on a Beacon Cloud installation. Disqualified records can be re-qualified by update their markers variable to contain the qualified marker

If disqualifying, you may set disqualify to the name of the marker to be set. The normal “Edit Data” screen sets the following markers: speeder, straightliner, badopen, foreigner. You can set any marker you want: this is just additional information.

Disqualified records are stripped of their qualified marker and any quota marker (e.g. /Quota_Sheet/marker) is prefixed with bad:.

Example URI

DELETE release.decipherinc.com/api/v1/surveys/survey/data/edit
URI Parameters
HideShow
survey
string (required) 

The survey to edit data in. You must have data edit permission for the project.

key
string (required) Example: uuid

The field used to match your participant data. This should be a unique variable. Supplying a non-unique key will change every matching record. This is implicitly null when creating new records.

data
array (required) 

An array of the participant records. Each element of the array is an object with the key being the column name matching a variable name, and the value the value you want to update. You can specify any amount of variables.

test
boolean (optional) Default: false 

Do not execute the edit, but return the changes that would be applied at the time of the call.

layout
int (optional) 

The id of a custom data layout. A custom export layout can relabel fields. If you exported some data with fields that have been relabelled in a layout and now are importing it back, you should use the same layout.

allVariables
bool (optional) Default: false 

Allow editing of notdp variables

mode
string (optional) Default: disqualify 

Either “delete” or “disqualify”

disqualify
string (optional) 

Marker to set.

Request
HideShow

In the below example request, we want to disqualify 3 records as speeders. mode is set to disqualify and disqualify is set to speeder.

Body
{
  "disqualify": "speeder",
  "data": [
    {
      "record": "2"
    },
    {
      "record": "4"
    },
    {
      "record": "5"
    }
  ],
  "mode": "disqualify",
  "key": "record"
}
Response  200
HideShow
Body
{
  "stats": {
    "fieldsIgnored": 3,
    "rows": 3,
    "fieldsErronous": 0,
    "rewritten": 3,
    "created": 0,
    "deleted": 0,
    "disqualified": 1,
    "unchanged": 2,
    "updated": 0,
    "bad": [],
    "fieldsUpdated": 3,
    "unseen": 0,
    "fieldsIdentical": 0,
    "inrows": 5,
    "unmatchedDeletions": 0,
    "fieldsProcessed": 6
  },
  "backup": "selfserve/1234/dataedit/data/old-results/014.results.*"
}

Modify Markers

Update Markers
PUT/api/v1/surveys/{survey}/data/edit/markers

Allows for updating participant markers that may have become outdated due to quota changes or data edits. Requires data edit permission for the project.

Return object:

  • comparison (object): Overview of what the new marker counts are compared against the current marker counts

  • backup (string): where is the previous version of the data? This can be restored by support or a shell user on a Beacon Cloud installation

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/data/edit/markers
URI Parameters
HideShow
survey
string (required) 

The survey to edit data in.

tablesBySheet
object (optional) Example: {"Gender": [0]}

Used to specify which sheets and tables to be updated. Each key of the object is a sheet name with a value that is an array of the table indexes. The first table on the sheet will have an index of 0. An empty array will include all tables for the sheet.

test
boolean (optional) Default: false 

Do not execute the edit, but return the changes that would be applied at the time of the call.

Request
HideShow
Body
{
  "test": "false",
  "tablesBySheet": {
    "Gender": [
      0
    ]
  }
}
Response  200
HideShow
Body
{
  "comparison": {
    "Gender": {
      "Male": {
        "new": 200,
        "old": 198
      },
      "Female": {
        "new": 168,
        "old": 170
      }
    }
  },
  "backup": "selfserve/1234/190702/data/old-results/011.results.*"
}

Import Data

Allows for modification of the participant data by specifying a file to import. Based on the arguments provided the columns in your file will either be matched to existing variables or they will be created as new variables. After appending new questions to your survey the data from your file will be imported. Rows without a matching key variable in the existng data will be created as new records. Creating new questions will perform a live merge.

Import Data
POST/api/v1/surveys/{survey}/respondents/import

Return object:

  • stats (object): overall statistics of what happened with your data edit requested:
    • created (int): number of new records created
    • deleted (int): number of records deleted
    • disqualified (int): number of qualified records disqualified or deleted
    • unseen (int): number of rows that did not match existing records when not creating new records
    • rewritten (int): records where data was modified
    • unchanged (int): records where your updated data did not cause changes
    • inrows (int): total amount of records processed (rewritten + unchanged + deleted + created)
    • fieldsIdentical (int): data update requests not done because existing data was identical. This counts individual cells
    • fieldsUpdated (int): data fields updated by the request
    • fieldsErronous (int): data supplied that was not valid
    • fieldsIgnored (int): cells ignored because uploading into legacy weight/record values (this is for surveys older than 2005)
    • fieldsProcessed (int): total fields processed
    • bad (array): invalid values detected during edit/update
    • rows (int): number of fields in your input data
    • unmatchedDeletions (int): records that you asked to be deleted but did not match existing records
  • backup (string): where is the previous version of the data? This can be restored by support or a shell user on a Beacon Cloud installation

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/respondents/import
URI Parameters
HideShow
survey
string (required) 

The survey to edit data in. You must have data edit permission for the project.

key
string (required) Example: uuid

The field used to match your participant data. This should be a unique variable. Supplying a non-unique key will change every matching record.

tabfile
unicode (required) 

tab delimited file to upload.

questions
array (required) 

an array of the variables corresponding to the column names in the data file. A question object is needed for new variables or variables where the column label differs from the report label. Each question is an object with:

  • index string – The index of this question in the data file.

  • reportLabel string – The label of the survey variable that this variable should be matched to when importing. Omit this argument if this should be a newly created variable.

  • label string – Required for new questions. When creating a new question this label will be the label of the new question.

  • title string – Required for new questions. The title to appear in reports for this question.

  • type – Required for new questions. One of the following:

    • single
      • generates a “radio” question
      • single ordinal answer
      • you must declare one or more values
    • multiple
      • generates a “checkbox”
      • multiple answers possible
      • you must declare one or more variables
    • number
      • generates a “float” question
      • any number allowed
    • text
      • generate a “text” question
      • any textual content allowed

  • variables – required for “multiple”, optional for others. This allows creating multiple variables for this question rather than just a single one. An array of objects containing:

    • title – human readable title for this variable.
    • column – the label containing the variable in the data file. Rather than pulling data from the question’s column/label, this variable will be read from this column. A separate question object should not be provided for the specified column.

Datasources

Create new questions in a survey (reporting or survey time). This corresponds to Import Data Element

List Datasources
GET/api/v1/surveys/{survey}/datasources

Returns a list of current datasources and their data. An array of datasources is returned: see the definition of PUT on what the content is.

Example URI

GET release.decipherinc.com/api/v1/surveys/selfserve/123/140001/datasources
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

Response  200
HideShow
Body
[
  {
    "ourKey": "source",
    "questions": [
      {
        "label": "vq6",
        "type": "text",
        "title": "vq1"
      }
    ],
    "reporting": false,
    "label": "ds5",
    "key": "source",
    "filename": "data_datasource_ds5.dat"
  }
]

Datasource

Operates on one specific datasource. Datasources are identified by an alphanumeric label which must not overlap with any labels in the survey. First use PUT surveys/.../datasources/label to create the datasource; then add data by targetting surveys/.../datasources/label/data.

Get
GET/api/v1/surveys/{survey}/datasources/{datasource}

Return the definition of a single datasource.

Example URI

GET release.decipherinc.com/api/v1/surveys/selfserve/123/140001/datasources/datasource
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

datasource
string (required) 

datasource label, must be composed of a-zA-Z_ characters only

Create
PUT/api/v1/surveys/{survey}/datasources/{datasource}

Create or update a datasource. When creating you decide what questions you have and whether they are virtual or not and what the matching key is. You can modify existing sets converting from real to virtual or vice versa, and deleting questions.

If you call PUT on an existing datasource, any attribute you specify will be replaced with its new version. Any attribute not mention will remain as is. Thus to add new questions, retrieve the original question configuration with GET , append your new questions and PUT the new one.

Changes to questions for a datasource with reporting set to False, or changes that set or clear reporting will require a live remerge.

Example URI

PUT release.decipherinc.com/api/v1/surveys/selfserve/123/140001/datasources/datasource
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

datasource
string (required) 

datasource label, must be composed of a-zA-Z_ characters only

reporting
bool (required) 

if true, the data is merged as virtual questions. This minimize setup time in live surveys. If false, data is created as real question. This requires a live merge.

elementOnly
bool (optional) Default: false 

if true, new elements will be created but will not be populated with data from a datasource. Attributes key and ourKey may be omitted when this is true. Only valid when reporting=false

key
string (required) 

the column in the data files uploaded that will be matched against our key

ourKey
string (required) 

the extraVariable or condition in the participant data that will be matched to the key

questions
array (required) 

an array of the questions that will belong to this datasource. Each question is an object with:

  • label string – a unique question label. It must not be used on any other question in this datasource or in the survey nor one of the reserved words (see KB)

  • column string (optional) – The column in the data file to be used to read the data. It defaults to the question label, if not specified. This allows you differentiate between how the data file is labelled versus how the question in the survey is labelled. Note that if you use variables the column assign happens per variable.

  • title string – human readable title

  • type – one of the following:

    • single
      • generates a “radio” question
      • single ordinal answer
      • you must declare one or more values
    • multiple
      • generates a “checkbox”
      • multiple answers possible
      • you must declare one or more variables
    • number
      • generates a “float” question
      • any number allowed
    • text
      • generate a “text” question
      • any textual content allowed

  • values – required for “single”. An array of possible answer values:

    • title – the human readable title of this value
    • value – the text that will be in uploaded data files that should match this answer. This can be a number (“1”) or any text (e.g. “male”). It is matched case insensitively, thus “MALE” in the input file will match a value of “male”
    • statValue – this converts to our value attribute and is used for averages in reporting or the value shown when downloading data. Optional.

  • variables – required for “multiple”, optional for others. This allows creating multiple variables for this question rather than just a single one. An array of objects containing:

    • column – the label containing the variable in the data file. Rather than pulling data from the question’s column/label, this variable will be read from this column
    • title – human readable title for this variable

Delete
DELETE/api/v1/surveys/{survey}/datasources/{datasource}

Remove the datasource definition and blank out any uploaded data files.

Example URI

DELETE release.decipherinc.com/api/v1/surveys/selfserve/123/140001/datasources/datasource
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

datasource
string (required) 

datasource label, must be composed of a-zA-Z_ characters only

Datasource data

Append, replace or delete data for a datasource. The data argument can be either an array of objects (JSON), a tab delimited file encoded as a single string (utf8 only) or an Excel 2007 file encoded as base-64.

Append
POST/api/v1/surveys/{survey}/datasources/{datasource}/data

Append data to this datasource’s data files. This merges the rows and columns. For any record, if the key for the datasource already exists in the current data file the columns of that record are updated with the new record. Columns with data in existing file and new uploaded data are replaced. Any records not matching existing data are appended to the file.

Example URI

POST release.decipherinc.com/api/v1/surveys/selfserve/123/140001/datasources/datasource/data
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

datasource
string (required) 

datasource label, must be composed of a-zA-Z_ characters only

data
object (required) 

either an array of objects, a single tab-delimited string or a base64-encoded Excel 2007 file

skipRemerge
bool (required) 

if true, the live remerge process is skipped. Please note, that skipping the remerge process will mean that existing participants might not match the new data or updated data will not be updated with the new data.

Replace
PUT/api/v1/surveys/{survey}/datasources/{datasource}/data

Truncates the existing data file then replaces with the provided data.

Example URI

PUT release.decipherinc.com/api/v1/surveys/selfserve/123/140001/datasources/datasource/data
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

datasource
string (required) 

datasource label, must be composed of a-zA-Z_ characters only

data
object (required) 

either an array of objects, a single tab-delimited string or a base64-encoded Excel 2007 file

Truncate
DELETE/api/v1/surveys/{survey}/datasources/{datasource}/data

Remove all existing data. The datasource definition itself is retained.

Example URI

DELETE release.decipherinc.com/api/v1/surveys/selfserve/123/140001/datasources/datasource/data
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

datasource
string (required) 

datasource label, must be composed of a-zA-Z_ characters only

Download
GET/api/v1/surveys/{survey}/datasources/{datasource}/data

Get all the existing data, as an array of objects.

Example URI

GET release.decipherinc.com/api/v1/surveys/selfserve/123/140001/datasources/datasource/data
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

datasource
string (required) 

datasource label, must be composed of a-zA-Z_ characters only

Survey metadata

Run Simulated Data

In order to run simulated data you must first initiate the process with a POST. You may then view the results of the run by using status api call, using the id provided by your POST request. The results of the status api call will include a status of “running” while the run is in progress. When complete the status will either be “finished” or “error”. If a status of “error” is returned it means simulated data was unable to complete. In this case more information will be available under “result”. When a status of “finished” is returned the “warnings” array will contain any warnings or errors returned by running simulated data.

Run Simulated Data
POST/api/v1/surveys/{survey}/sst

Begin running simulated data.

Example URI

POST release.decipherinc.com/api/v1/surveys/selfserve/123/140001/sst
URI Parameters
HideShow
survey
string (required) Example: selfserve/123/140001

path to survey

count
int (optional) Default: 200 

The number of simulations to run. Maximum: 2000

qualified
bool (optional) Default: False 

Submit mostly qualified responses

skip_validate
bool (optional) Default: False 

ignores question validation to maximize test efficiency

respect_optionals
bool (optional) Default: False 

leaves some optional answers blank

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "3jd7qyadpgjbxu6t"
}

Close survey

Close
POST/api/v1/surveys/{survey}/state/close

Closes a survey. The survey’s state is modified from any other state to “closed” immediately, preventing new participants from starting the survey. Requires survey edit permission for the project. Decipher 29.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/state/close
URI Parameters
HideShow
survey
string (required) 

path to survey to affect

now
boolean (required) Default: false 

by default participants have 1 hour from close time to finish a survey if they already started. Setting to true closes immediately

Launch survey

Launch
POST/api/v1/surveys/{survey}/state/live

Launches a survey. Goes through the launch process for a survey. If there are any warnings those will be returned and the survey will not be launched. Otherwise the surveys state will be changed to “live”. Requires survey edit permission for the project.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/state/live
URI Parameters
HideShow
survey
string (required) 

path to survey to affect

relaunch
boolean (optional) Default: false 

This is required if a survey is in the closed state and needs to be set live.

ignore_warnings
boolean (optional) Default: false 

This will ignore other survey warnings including: open tasks, incompatible elements, missing project parameters, and outdated translations.

ignore_kinesis
boolean (optional) Default: false 

This will ignore any kinesis errors when setting the survey live and will skip any syncing with kinesis.

ignore_fulcrum
boolean (optional) Default: false 

This will ignore any fulcrum errors when setting the survey live and will skip syncing questions and changing the survey state on fulcrum.

ignore_sst
boolean (optional) Default: false 

Passing this will ignore any sst warnings and launch the survey without valid progress data. Skipping this is not recommended and may result in uncaught survey errors and an inaccurate progress bar.

Get Launch Warnings

Warnings
GET/api/v1/surveys/{survey}/state/live/warnings

Returns any launch warnings that will appear when launching the survey.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/state/live/warnings
URI Parameters
HideShow
survey
string (required) 

path to survey

Survey Environment

Evaluate
POST/api/v1/surveys/{survey}/evaluate

Evaluates code within a specific survey environment. This allows you to find out the value of logic conditions such as q3.r5.val within a specific participant’s survey context. The context can be omitted; in that case the last submitted state is used (this is most useful when debuggin where you know no new data appears). Decipher 29

This is equivalent to modifying the survey.xml to add an <exec> block that prints out the valuate.

This API is available from the command line using the beacon eval tool. Run beacon eval survey/path to open up a shell that lets you evaluate multiple commands using this API. This command takes an optional state ID.

The returned object has a stdout value that corresponds to what would be printed in a shell. Thus if you ask for a string, e.g. q1.r1.val the Python representation of a string is returned, i.e. 'Hello\n'. You can use print q1.r1.val to avoid that. The returned state value can be passed in again to ensure the same evaluation environment – this is useful if you called the API without an explicit state.

Any changes to question data (e.g. q3.r1.val = “foo”) or persistent variables will be reset next time you call the API, as the state is reloaded. Assignment to local variables may or may nor persistent, just like in the normal data collection.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/evaluate
URI Parameters
HideShow
survey
string (required) 

path to survey. You must be able to build the survey

cond
string (required) 

Python condition to evaluate. This works like the Python command line shell: you can send a multi-line loop

state
string (required) 

The ID of the state to enter. After submitting a survey page, view the source code and look for the hidden “state” variable.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "state": "2498cbe94fb82cd2c153edc73370aa99ce95592fQ000001Q000002a7",
  "stdout": "'Hello Professor Falken'\n"
}

Quota

Get Quota
GET/api/v1/surveys/{survey}/quota

Retrieves quota cell definition and current state. Decipher 28

For full KB documentation, see Quotas Guide: Limit and Monitor Project Sample. Concepts:

  • A quota file (quota.xls) contains multiple sheets.

  • The survey quota element executes all tables from one sheet.

  • Tables reference markers. A marker has either a condition (E.g. set if Male - q1.r1)) or is a plus marker.

  • A quota cell defines number of participants you want that have 1 or more markers set.

  • If a participant is eligible for multiple cells, the cell with highest priority is chosen, otherwise the cell with the least filled percentage.

  • If properly eligible, the participant receives one quota marker per table identifying the exact cell, which is a combination of the sheet and markers involved. For example, /Sheet1/Male/18-25 (note that quotas created with the survey editor will have auto-assigned IDs for markers e.g. /New Quota/AoAos/bo8Oi).

  • Every plus marker the participant is assigned is also set in addition to the quota cell marker, e.g. concept1 and /Concepts/concept1.

This API returns an object with the properties:

  • markers: Maps each quota cell marker name (e.g. /Sheet1/Male/18-25) to an object describing its current state. This object contains:

    • complete: The number of completed and qualified participants with that marker.
    • pending: The number of participants who have been set the marker and have been active within the last 15 minutes, but have not yet completed.
    • limit: The current effective cell limit (when using soft quotas this may be different from the hard limit).
    • oq: The number of participants who qualified for the cell but were terminated because the cell had already reached the limit.

  • sheets: Maps sheet names to sheet definitions. Each sheet definition is an array of tables. Each table contains:

    • description: The table name, an optional description entered.
    • cellCount: The maximum number of quota cells selected when hitting this table (normally just 1).
    • tableTotal: The table total. This is used solely for soft quotas and percentage-based selection.
    • tableIndex: The table index in relation to the sheet.
    • cells: An array of the quota cells. Each cell is again an object with these properties:
      • marker: Name of the quota cell marker set by this cell. Index into markers above to find the counts.
      • components: The markers (see defines and plus) that make up this quota marker.

  • defines: Maps a marker name to an object:

    • cond: The logic condition required to qualify for this marker. If condition is null, this is a plus marker.
    • description: The alternative text for a marker shown in the Response Summary.

  • plus: An array of plus markers defined in this quota.

  • priority: Maps quota cell markers (e.g. /Sheet1/Male/18-25) to priority levels. Those not mentioned have priority 0.

  • stopped: An object with the quota cell markers of cells that were stopped in the Response Summary, the user that stopped the cell and the timestamp of when the cell was stopped. Those have a temporary hard limit of 0 until resumed.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/quota
URI Parameters
HideShow
survey
string (required) 

path to survey

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "markers": {
  "/New Quota (1)/two": {
   "limit": 50,
   "pending": 0,
   "oq": 0,
   "complete": 0
  },
  "/New Quota/AoAos/bo8Oi": {
   "limit": 20,
   "pending": 0,
   "oq": 0,
   "complete": 0
  },
  "/New Quota (1)/one": {
   "limit": 50,
   "pending": 0,
   "oq": 0,
   "complete": 0
  }
 },
 "priority": {
  "/New Quota (1)/one": 2
 },
 "plus": [
  "four",
  "five",
  "three",
  "two",
  "one"
 ],
 "sheets": {
  "New Quota (1)": [
   {
    "cellCount": 1,
    "tableTotal": 250,
    "tableIndex": 0
    "cells": [
     {
      "marker": "/New Quota (1)/one",
      "components": [
       "one"
      ]
     },
     {
      "marker": "/New Quota (1)/two",
      "components": [
       "two"
      ]
     }
    ]}]
 },
 "stopped": {
  "/New Quota/AoAos/s9oVa": "erwin@decipherinc.com on 02/24/2015 12:48"
 },
 "defines": {
  "XiiZn": {
   "cond": "(q1.r6)",
   "description": "55-64"
  },
  "LvmQy": {
   "cond": "(q1.r2)",
   "description": "18-24"
  }
 }
}

Quota Limits

Update Quotas
PUT/api/v1/surveys/{survey}/quota/edit

Updates quota limits. Requires Response Summary: edit permission for the project. Use Quota API to access quota definitions.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/quota/edit
URI Parameters
HideShow
survey
string (required) 

path to survey

limits
object (required) 

Contains the keys and new limits. The key for cell is the full marker name and table is the sheet/tableindex. Use the Quota API to retrieve the quota table sheet and index.

Request  Set Cell Limits
HideShow
Body
limits = {"/Gender/TDW7j":"125", "/Gender/gp00q": "75"}
Request  Set Table Limits:
HideShow

This example updates the limit for the second table (index 1) on sheet “Gender”

Body
limits = {"Gender/1": "500"}
Request  Remove Table Limits
HideShow

This example removes the limit for the second table (index 1) on sheet “Gender”

Body
limits = {"Gender/1": "inf"}
Request  Set Limit to Range
HideShow
Body
limits = {"Gender/1": "500", "/Gender/TDW7j":"200-500", "/Gender/gp00q": "0-300"}
Request  Set Limit to Percentages
HideShow
Body
limits = {"Gender/1": "500", "/Gender/TDW7j":"70%", "/Gender/gp00q": "30%"}
Request  Setting Priorities
HideShow
Body
limits = {"/Gender/TDW7j":"125:3", "/Gender/gp00q": "75"}

Monitoring a survey's warnings

Get Warnings
GET/api/v1/surveys/{survey_path}/warnings

Retrieve project warnings for a survey.

The returned object contains the following properties:

  • name – survey name

  • path – survey path

  • company – company ID

  • events – an array of events consisting of the following properties (subject to data retention rules)

    • timestamp – time of event occurrence or observation
    • type – event type (one of ‘blocks’, ‘missing_resources’, ‘exceptions’, or ‘quota_misses’)
    • details – an object consisting of properties that are specific to the event type

  • counts – full event counts

Only events experienced by non-users (i.e., logged-out participants) in non-testing surveys are reported. Best efforts are made to eliminate duplicate events from the results.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey_path/warnings
URI Parameters
HideShow
survey_path
str (required) 

survey path

types
array (optional) Default: "blocks,missing_resources,exceptions,quota_misses" 

restrict events returned to just these types

start
date (optional) Example: YYYY-MM-DD

restrict events returned to just those occurring on/after this date (in ISO 8601 format)

end
date (optional) Example: YYYY-MM-DD

restrict warnings counts to just those occurring on/before this date

Survey files list

List Files
GET/api/v1/surveys/{survey}/files

Retrieves a list of system and static files relevant to a survey

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/files
URI Parameters
HideShow
survey
string (required) 

path to survey

Response  200
HideShow
Body
[
  {
    "filename": "survey.xml",
    "modified": "2014-11-18T11:37:45Z",
    "size": 65584
  },
  {
    "filename": "sst.txt",
    "modified": "2012-03-05T23:29:17Z",
    "size": 0
  }
]

Survey file access

Download File
GET/api/v1/surveys/{survey}/files/{filename}

Allows direct access to some of the configuration files that make up a survey. Use the List call above to find out what files are specifically available for this survey.

  • survey.xml – survey’s main content

  • quota.xls – Excel 97 file defining quotas

  • quota.xls.log – this log file contains debug information stored on every quota invocation

  • survey.log – additional debug data related to the survey

  • data/exit.log – one entry for each participant exiting the survey

  • virtual-timing.txt – virtual question performance

  • static/* – all uploaded static resources

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/files/filename
URI Parameters
HideShow
survey
string (required) 

path to survey

filename
string (required) 

filename to download

Upload/Replace File
PUT/api/v1/surveys/{survey}/files/{filename}

Allows a new file to be uploaded or an existing file to be replaced. When uploading a survey.xml, only a survey that would successfully load are allowed and only surveys in dev or testing state can be modified. If you override the last check beware not to modify the datamap for your survey, as no conversion process is done by this call.

If an invalid file is uploaded, the 400 error code is returned. If an error is returned from a survey.xml, the body will contain a list of errors in the extra property. This will be an array of error objects. An error object will have type set to either parse or survey. Parse errors occur during XML parsing. Survey errors occur during validation of survey content (i.e. attributes and values).

A list of the allowed file types can be found here.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/files/filename
URI Parameters
HideShow
survey
string (required) 

path to survey

filename
string (required) 

filename to upload

contents
file (required) 

file to upload

validate
boolean (optional) Default: true 

Only applies when uploading survey.xml. Validate survey.xml prior to saving it.

overwriteLive
boolean (optional) Default: false 

allow updates to live or closed surveys

location
string (required) Default: root 

location to upload. Options: root (System Only), static (Publicly Available)

convertToTab
boolean (optional) Default: false 

allow .xls, .xlsx, .txt, .dat, and .csv file conversion to tab-delimited .dat

Response  200
HideShow
Body
{
    filename: "survey.xml"
}
Response  400
HideShow
Body
{
  "$error": "Bad content. Additional error in body.",
  "$code": 400,
  "extra": [
    {
      "column": 220,
      "processed": "<survey autosave=\"0\" setup='time,term,quota' autosaveKey=\"\" compat=\"118\" extraVariables=\"url,record,list,page,source\" lang=\"english.utf8\" name=\"Kitchen Sink Survey (remotely modified)\" pipeAltLabels=\"1\" state='testing'> <>",
      "file": "demo/kitchensink/temp-api/survey.xml",
      "line": 2,
      "type": "parse",
      "message": "not well-formed (invalid token)"
    }
  ]
}
Response  400
HideShow
Body
{
  "$error": "Bad content. Additional error in body.",
  "$code": 400,
  "extra": [
    {
      "tag": "radio",
      "type": "survey",
      "label": "q1",
      "error": "Extra unrecognized argument given: whatever"
    },
    {
      "line": 1243,
      "tag": "col",
      "type": "survey",
      "label": "c8",
      "error": "Extra unrecognized argument given: xyzzy"
    }
  ]
}

Delete File
DELETE/api/v1/surveys/{survey}/files/{filename}

Allows the user to delete any file type that can be uploaded in the survey directory. Version control may store past revisions for specific files in the survey directory. The force flag is required if the survey is live or closed. If used incorrectly this can cause data loss. If an invalid file is attempted to be deleted, a 400 response will return. On successful deletion of the file a 200 response will return. The survey log and user audit log will contain an entry for who deleted what specific file.

Example URI

DELETE release.decipherinc.com/api/v1/surveys/survey/files/filename
URI Parameters
HideShow
survey
string (required) 

path to survey

filename
string (required) 

filename to delete

location
string (required) Default: root 

location to upload. Options: root (System Only), static (Publicly Available)

force
boolean (optional) Default: false 

force delete the file if the survey is live or closed (warning: This can cause data loss if used incorrectly)

Get File Headers

List File Headers
GET/api/v1/surveys/{survey}/files/headers

Retrieves a list of headers from a .dat or .txt file in the root directory of the project.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/files/headers
URI Parameters
HideShow
survey
string (required) 

path to survey

filename
string (required) 

file name to retrieve headers from.

Response  200
HideShow
Body
[
  "email",
  "firstname",
  "lastname",
  "occupation"
]

Edit File

Edit File
POST/api/v1/surveys/{survey}/files/edit

Edits a single row of a .dat file in a survey’s root directory. index is required when editing or deleting a row. values are required when adding or editing a row.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/files/edit
URI Parameters
HideShow
survey
string (required) 

path to survey

filename
string (required) 

file to edit

op
string (required) 

operation on the file Options: add (add a row), edit (edit a row), delete (delete a row)

values
object (required) 

an object that has a key for the column and value for the cell to be edited

index
integer (required) 

the index of the row to be edited

Request
HideShow
Body
{
    "filename": "test_file.dat",
    "op": "edit",
    "index": 3,
    "values": {
      "first_name": Max,
      "last_name": Power
    }
}
Response  200
HideShow
Body
{}

Panels

Manage Kinesis Panels from Decipher.

Panel registration survey

Get Registration Survey
GET/api/v1/panels/{panel_id}/registration

Get the panel’s Decipher registration survey’s path.

Example URI

GET release.decipherinc.com/api/v1/panels/panel_id/registration
URI Parameters
HideShow
panel_id
string (required) 

the panel’s numeric ID

instance
string (required) 

filter results to just this Kinesis Panel instance/host

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "path": "selfserve/53a/100100"
}

Panels

List Kinesis Panels
GET/api/v1/surveys/{survey}/panels

Retrieves all Kinesis Panels accessible to a survey. (Requires access to the survey and installation of the Kinesis Panel instance’s API key in the survey’s path.)

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/panels
URI Parameters
HideShow
survey
string (required) 

path to survey

instance
string (optional) 

filter results to just this Kinesis Panel instance/host

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "instance": "some.panel.com",
    "panels": [
      {
        "id": "1",
        "name": "My Little Panel"
      },
      {
        "id": "4",
        "name": "My Cool, New Panel"
      }
    ]
  }
]

Panel datapoints

List Panel Datapoints
GET/api/v1/panels/{panel_id}/datapoints

Returns the datapoints belonging to the specified panel. The returned objects contain the following information:

  • group – group the datapoint belongs to

  • system_field – system field referencing the datapoint

  • text – the datapoint’s question text or description

  • modified – the modification time of the datapoint

  • label – the unique, alphanumeric identifier for this question

  • type – datapoint’s question type

  • fingerprint – hash of the datapoint, ignoring text and export value changes

  • choices – array of answer option objects, comprised of:

    • export_value – export value
    • value – unique (across entire panel) numeric ID
    • choice – answer option text

Example URI

GET release.decipherinc.com/api/v1/panels/panel_id/datapoints
URI Parameters
HideShow
panel_id
string (required) 

panel’s numeric ID

instance
string (required) 

the Kinesis Panel instance/host

survey
string (optional) 

a survey with the panel’s API key in its path

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "group": null,
    "system_field": "gender",
    "text": "Gender",
    "modified": 1468518354,
    "label": "Qgender",
    "fingerprint": "42a637",
    "choices": [
      {
        "export_value": 10,
        "value": 1,
        "choice": "Male"
      },
      {
        "export_value": 11,
        "value": 2,
        "choice": "Female"
      },
      {
        "export_value": 99,
        "value": 247,
        "choice": "Prefer not to say"
      }
    ],
    "type": "radio"
  },
  {
    "group": null,
    "system_field": "zip-postal_code",
    "text": "What is your zip code?",
    "modified": 1459877107,
    "label": "Qzip",
    "fingerprint": "c74d97",
    "choices": [],
    "type": "openend"
  }
]

Push datapoints
POST/api/v1/panels/{panel_id}/datapoints

Create new datapoints on a Kinesis Panel from a Decipher survey’s questions.

Example URI

POST release.decipherinc.com/api/v1/panels/panel_id/datapoints
URI Parameters
HideShow
panel_id
string (required) 

the panel’s numeric ID

instance
string (required) 

the Kinesis Panel instance/host

survey
string (required) 

the survey containing the questions to create as panel datapoints

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "successful": [
    "q1",
    "q2",
    "q3"
  ],
  "failed": [
    {
      "label": "q4",
      "error": "Choices not allowed for type"
    }
  ]
}

Research Hub

Examine and manage users on the system.

User provisioning

Resource properties:

  • id the numeric user ID

  • supervisor boolean: true if the user is a supervisor

  • staff boolean: true if the user has the fully powered staff account

  • company the company the user belongs to

  • subdirectory if not null, the user is restricted to creating projects only within this directory

  • type either “s” for shared user or “f” for a full users

  • login the login name of the user. This is the email address for full users, and username for shared users

  • fullname the full human name of the user

  • last_login date of last login

  • last_login_where IP address of last login

  • lockedout_until If user has entered his password too many times, this is the earliest date he can try again

  • expires_on If user account is set to automatically expires, this is the expiry date

  • last_password_change date of last password change

List Users
GET/api/v1/rh/users

What users exist on the system? Returns an array of user objects.

Example URI

GET release.decipherinc.com/api/v1/rh/users
URI Parameters
HideShow
company
id (optional) 

show users only from this particular company ID. A staff user will by default see all users in all companies but can choose to see only a specific one. A regional supervisor user will see only users in their own company but can select one of the companies they supervises.

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
 {
  "last_login_where": "8.8.8.8",
  "supervisor": false,
  "subdirectory": null,
  "type": "f",
  "company": 1178,
  "id": 104,
  "last_password_change": "2014-10-08T21:41:38Z",
  "last_login": "2014-10-09T15:12:02Z",
  "active": true,
  "fullname": "Joe Q. User",
  "lockedout_until": null,
  "login": "joe@example.com",
  "expires_on": null,
  "staff": true
 },

Managing individual users

Modify Users
PUT/api/v1/rh/users/{user}

Update some property about the user. Each change requires an explanation which is added to the audit log of the changer and the change. You must be able to edit the user, i.e. you are supervisor for the company or staff user.

Example URI

PUT release.decipherinc.com/api/v1/rh/users/user
URI Parameters
HideShow
user
string (required) 

either the ID or email address of the user to affect

why
string (optional) 

explanation for the status change. This is added to the user’s audit log

active
boolean (optional) 

set this to false to disable a user and true to re-enable.

Sending password reset email

Create Password Reset
POST/api/v1/rh/users/{user}/send-password-reset

Sends a password reset email to the user specified. You must be able to edit the user, i.e. you are supervisor for the company or staff user.

Example URI

POST release.decipherinc.com/api/v1/rh/users/user/send-password-reset
URI Parameters
HideShow
user
string (required) 

either the ID or email address of the user to email

Whiteboard

Get Whiteboard
GET/api/v1/rh/users/{user}/whiteboard

Get a user’s “whiteboard”, containing preferences for e.g. Builder and Research Hub.

Example URI

GET release.decipherinc.com/api/v1/rh/users/user/whiteboard
URI Parameters
HideShow
user
string (required) 

either the ID or email address of the user to affect

Whiteboard

Clear Whiteboard
DELETE/api/v1/rh/users/{user}/whiteboard/{fragment}

Clear part of a user’s whiteboard. The fragment should be either e.g. portal or builder to clear all settings related to Research Hub and builder, or e.g.builder/lumos.style.theme to clear one specific setting (here, the default theme name).

Returns the data in the entry that was cleared. For list of possible whiteboard items, issue the GET call.

Example URI

DELETE release.decipherinc.com/api/v1/rh/users/user/whiteboard/fragment
URI Parameters
HideShow
user
string (required) 

either the ID or email address of the user to affect

fragment
string (required) 

e.g. portal or portal/companySelection

Company management

Resource properties:

  • id the numeric user ID

  • name name of the company

  • description longer description of the company

  • min_password_length minimum password length of passwords for users within the company (cannot be less than 7)

  • min_classes number of character classes in passwords (cannot be less than 2)

  • password_expire_days days between required password changes

  • allow_shared_accounts new shared accounts can be created

  • inactivity_timeout default timeout for sessions (in seconds)

  • max_invalid_attempts invalid attempts before accounts are locked out (cannot be less than 6)

  • created_by user ID of user who created the company

  • created_on when was this company created?

  • updated_on when was this company’s data last updated?

  • updated_by who updated the company last?

  • expires_on expiration for the company (accounts will not be able to login past this time). This will never be null: companies that never expire still expire in the year 9999.

  • subdirectories information for subdirectories that belong to the company

  • is_supercompany true if a regional super-company

  • supercompany if not null, the ID of super-company this sub-company belongs under

  • archive_days: if not null, override server default period of days before an idle, closed project is archived

  • clear_data_days: if not null, override server default period of days before an archive project has respondent (but not survey configuration) data removed

List Companies
GET/api/v1/rh/companies

What companies exist on the system? Returns an array of user objects. Supervisor access required.

Example URI

GET release.decipherinc.com/api/v1/rh/companies

Survey list

Get Projects
GET/api/v1/rh/companies/{company}/surveys

This call retrieves Research Hub’s information about projects available for companies. Generally you should specify “all” as company parameter: the project accessible to you may not all be owned by your company. To select multiple companies, keep the “company” variable to “all” and set a “companies” variable to a list of company IDs.

A search query can be what you would normally specify in the portal. Review the Advanced Syntax listed Search Capabilities – for example, pass the query variable set to #sometag or user:joe@example.com for special queries, or kittens for a normal text search.

The returned array contains these properties. Remember that you can pass select to any query to get just a subset of them.

  • Survey Identity:

    • path – full survey path, e.g. selfserve/123/4567
    • title
    • owner – what company own this survey?
    • description – additional description entered in the portal
    • state – dev, testing, live or closed
    • tags – array of tags applied
    • directory – combination of company name, subdirectory and a client tag

  • Extras Configured

    • hasSavedReport
    • hasDashboard

  • Personal Settings

    • archived – true if hidden for your account via the archiving function
    • favorite – true if you marked this project as favorite

  • Participant Data:

    • dateLaunched – date survey was set live
    • startTime – first complete date and time
    • finishTime – last complete date and time
    • clickthrough – number of clickthroughs
    • total – total participants (OQ + term + qualified)
    • qualified – qualified completes
    • medianQtime – median completion time (in seconds) for qualified participants. Not available (and always null) for Delphi surveys; use the response summary API instead.
    • today – completes today
    • averageQtime – mean completion time (in seconds) for qualified participants. Not available (and always null) for Delphi surveys; use the response summary API instead.

  • Survey Configuration:

    • compat – compatibility level (compat attribute in survey.xml)
    • questions – number of questions in the survey visible to the participant
    • type – beacon=1, email=2, spss=4
    • lang – primary language, generated as a pair of [language id, language description]
    • otherLanguages – list of any other languages, each item being a tuple like above
    • sampleSources – participant sources used – this is an array of list values, e.g. [“100”, "102]

  • Access History:

    • active – active surveys have been accessed, edited or had had completes within 3 days
    • lastAccessBy – null or an object with properties: email, name and id (user ID) of who last accessed this survey
    • createdBy – null or an object with properties email, name and id of the survey creator
    • lastEditBy – as above for last edit
    • myAccess – when did YOU last access this survey?
    • myEdit – when did YOU last edit this survey?
    • accessed – has this survey been accessed in the last 3 days? This is a subset of active
    • lastEdit – when did someone last edit this survey?
    • lastAccess – when did someone last access this survey?
    • closedDate – null or a timestamp of when the survey was closed last
    • createdOn – a timestamp of when the survey was created
    • lastQuotaEdit – null or a timestamp of when the quota.xls was modified last
    • lastSurveyEdit – a timestamp of when the survey.xml was modified last

  • Misc:

    • matched – if query was passed, object containing field matched and content of that field with match highlighted

Example URI

GET release.decipherinc.com/api/v1/rh/companies/company/surveys
URI Parameters
HideShow
company
string (required) 

the company ID or name of the company whose project you want to see. Specify self for your own company, or all for all companies (recommended)

query
string (optional) 

a search query

companies
array (optional) 

show only companies with these IDs (used with company=all)

permission
string (optional) 

require a minimum permission level (e.g. survey.edit)

Create Project
POST/api/v1/rh/companies/{company}/surveys

Create a new project.

Example URI

POST release.decipherinc.com/api/v1/rh/companies/company/surveys
URI Parameters
HideShow
company
string (required) 

the company ID or name of the company where you want the project to be created. Specify self for your own company.

name
string (required) 

Name of project shown in Research Hub

ptype
string (required) 

Project type (Types: beacon, email, spss)

category
string (optional) 

Project category (Query GET /api/v1/rh/surveys/categories for valid options.)

subdirectory
int (optional) 

Subdirectory ID number

description
string (optional) 

Description of project

tags
array (optional) 

List of tags

prefPath
string (optional) 

Path of the project (e.g. abc20001). Only lowercase letters, numbers, and underscores are allowed.

lang
string (optional) 

Language of the project

Research Hub Categories

Get Categories
GET/api/v1/rh/surveys/categories

Return list of possible categories.

Example URI

GET release.decipherinc.com/api/v1/rh/surveys/categories
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {
        "key": "",
        "text": "No Selection"
    }, {
        "key": "auto",
        "text": "Automotive"
    }, {
        "key": "beauty",
        "text": "Beauty/Cosmetics"
    },
    ...
]

Research Hub Historical Surveys

Get Historical List
GET/api/v1/rh/surveys/historical

Returns a list of survey paths the current user can access for any existing as well as historical and archived survey.

Unlike the normal portal survey list, this returns all surveys regardless of current company selection for staff.

Example URI

GET release.decipherinc.com/api/v1/rh/surveys/historical
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  "selfserve/53c/160615",
  "selfserve/53c/181216",
  "selfserve/53c/1611272",
  "selfserve/53c/160616"
]

Research Hub Survey

Get Project information
GET/api/v1/rh/surveys/{survey}

This will get the information shown in the Research Hub for an individual survey.

Example URI

GET release.decipherinc.com/api/v1/rh/surveys/survey
URI Parameters
HideShow
survey
string (required) 

Path of the survey.

Update Project information
PUT/api/v1/rh/surveys/{survey}

This call is used to update information in the Research Hub tied to a survey, and requires either survey.edit or data.edit permission on the survey. Omitted parameters are left unchanged. Returns back the new state of the resource.

Valid categories:

  • empty string (No Selection)

  • auto (Automotive)

  • beauty (Beauty/Cosmetics)

  • beverage_alcohol (Beverages - Alcoholic)

  • beverage_non_alcohol (Beverages - Non-alcoholic)

  • business (Business)

  • parenting (Children & Parenting)

  • loyalty (Coalition/Loyalty Programs)

  • credit_cards (Credit Cards)

  • tourism (Destinations & Tourism)

  • education (Education)

  • computer (Electronics/Computer/Software)

  • entertainment (Entertainment & Leisure)

  • explicit (Explicit Content)

  • clothing_dept_store (Fashion & Clothing - Department Store)

  • clothing_other (Fashion & Clothing - Other )

  • finance (Finance, Banking Investing & Insurance)

  • food (Food/Snacks)

  • gambling (Gambling/Lottery)

  • politics (Government & Politics)

  • healthcare (Healthcare/Pharmaceuticals)

  • home_appliances (Home (Utilities, Appliances))

  • home_entertainment (Home Entertainment (DVD, VHS))

  • home_improvement (Home Improvement/Real Estate/Construction)

  • information_tech (IT (Servers, Databases, etc))

  • media (Media & Publishing)

  • personal_care (Personal Care/Toiletries)

  • pets (Pets)

  • restaurants (Restaurants)

  • sensitive (Sensitive Content)

  • smoking (Smoking/Tobacco)

  • social (Social Research)

  • fitness (Sports, Recreation, Fitness)

  • telecom (Telecommunications (phone, cell phone, cable))

  • toys (Toys)

  • transportation (Transportation)

  • travel_airlines (Travel - Airlines)

  • travel_hotels (Travel - Hotels)

  • travel_services (Travel Services/Agency/Booking)

  • video_games (Video Games)

  • internet (Websites/Internet/E-Commerce)

Example URI

PUT release.decipherinc.com/api/v1/rh/surveys/survey
URI Parameters
HideShow
survey
string (required) 

Path of the survey. survey.edit or data.edit permission required.

description
string (optional) 

A description for the survey.

category
string (optional) 

A category key. Query GET /api/v1/rh/surveys/categories to see all possible options. Empty string is passed to return to the default state of “No Selection”.

keep
boolean (optional) 

if set to true, suppress any automated archival of this suvey. Equivalent of issuing the command touch keep in the shell.

Request
HideShow
Body
{
  "category": "food",
  "description": "This survey is about food!",
  "keep": false
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "path": "survey/path",
  "category": "food",
  "description": "<p>This survey is about food!</p>",
  "keep": false
}

Panels

List Company Panels
GET/api/v1/rh/companies/{company}/panels

Retrieves all Kinesis Panels accessible to a company. (Requires access to company and installation of the Kinesis Panel instance’s API key.)

Example URI

GET release.decipherinc.com/api/v1/rh/companies/company/panels
URI Parameters
HideShow
company
string (required) 

can be “self” for your own company, a numeric company ID or company name

instance
string (optional) 

filter results to just this Kinesis Panel instance/host

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "instance": "some.panel.com",
    "panels": [
      {
        "id": "1",
        "name": "My Little Panel"
      },
      {
        "id": "4",
        "name": "My Cool, New Panel"
      }
    ]
  }
]

Preferences

Manage company-wide preferences. Following preferences currently exist:

  • fwu – how should fixed-width unicode options be presented? One of:
    • compat (default): compat <125 surveys show both normal and unicode variants; 126+ only unicode
    • unicode: only unicode variant shown
    • both: both variants shown for all compat levels
    • plain: only non-unicode variant shown.

List Preferences
GET/api/v1/rh/companies/{company}/preferences

Retrieves all preferences for a specific company.

Example URI

GET release.decipherinc.com/api/v1/rh/companies/company/preferences
URI Parameters
HideShow
company
string (required) 

can be “self” for your own company, a numeric company ID or company name

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "fwu": "compat",
  "appliedDefaults": [
    "fwu"
  ]
}

Preferences update

Update Preferences
PUT/api/v1/rh/companies/{company}/preferences/{key}

Set a preference to a new value.

Example URI

PUT release.decipherinc.com/api/v1/rh/companies/company/preferences/key
URI Parameters
HideShow
company
string (required) 

company to update the preference for

key
string (required) 

the preference to update

value
string (required) 

. the new value to update to

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Preferences history

Get Preference History
GET/api/v1/rh/companies/{company}/preferences/{key}/history

View a list of all changes to a specific preference. Returns:

  • new the new value of the preference

  • previous the previous value of the preference

  • user_id account responsible for change

  • tstamp time of change

Example URI

GET release.decipherinc.com/api/v1/rh/companies/company/preferences/key/history
URI Parameters
HideShow
company
string (required) 

company ID or name

key
string (required) 

name of preference

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "new": "compat",
    "previous": "unicode",
    "user_id": 104,
    "tstamp": "2014-10-21T14:27:38Z"
  },
  {
    "new": "unicode",
    "previous": "compat",
    "user_id": 104,
    "tstamp": "2014-10-21T14:20:51Z"
  },
  {
    "new": "compat",
    "previous": null,
    "user_id": 104,
    "tstamp": "2014-10-21T14:20:35Z"
  }
]

Usage stats

Calculate Usage
GET/api/v1/rh/usage

Outputs data generated by the usage page, combined with a breakdown of qualifieds by device type. Note that this data is only accessible 24-48 hours after: yesterday’s participant data is converted at 10pm (Beacon Cloud) or 1am (Ares).

Fields returned:

  • qualified_devices: an object containing properties “.” (desktop), “f” (featurephone), “s” (smartphone), m (misc mobile device), t (tablet)

  • clickthrough_devices: as above, but for all clickthroughs

  • users: distinct active users

  • surveys: distinct active live surveys

  • clickthrough: total clickthroughs in live surveys

  • qualifiedCompletes: total qualifieds

  • surveyPaths: survey paths involved in the active live surveys calculation

  • overquota

  • terminated

  • standardCompletes / mobileCompletes: internal split for Decipher billing purposes

  • videos, videoViews, views0_5Min, views5_10Min, views10Min: Brightview usage activity

  • emailSends, emailCampaigns, spamComplaints, spamRate: email campaign activity

  • launchedSurveys

  • vtResponsesSeparated: list of response counts per video testimonial question

  • imgUploadResponsesSeparated: list of response counts per image upload question

  • event_* – detailed usage stats (reports run, dashboards created etc.)

  • hubStorage

  • importedCompletes, cleanedData

  • publishedDashboards: count of all published dashboards

Example URI

GET release.decipherinc.com/api/v1/rh/usage
URI Parameters
HideShow
start
datetime (required) 

start date

end
datetime (required) 

end date

company
int (optional) 

restrict only to this company’s stats

excludeDecipher
bool (optional) 

exclude Decipher-launched projects

Monitoring a company's project warnings

Get Company's Warnings
GET/api/v1/rh/warnings/summary

Retrieve summaries of project warnings for companies’ projects.

Each project in the returned array consists of the following properties:

  • Project meta information

    • name – project name
    • path – project path
    • company – company ID
    • lastEditBy – the person who last edited this survey

  • Project event counts

    • blocks – occurrences of participants being blocked from entering the survey for various reasons
    • missing_resources – occurrences of a nonexistent static resource (e.g., image or script) being requested by the survey
    • exceptions – fatal errors experienced by participants
    • quota_misses – occurrences of a participant failing to qualify for a quota table

Events are summarized as counts occurring during the period specified. Only events experienced by non-users (i.e., logged-out participants) in non-testing surveys are reported. Best efforts are made to eliminate duplicate events from the results.

Example URI

GET release.decipherinc.com/api/v1/rh/warnings/summary
URI Parameters
HideShow
companies
array (optional) 

restrict projects to just those owned by companies with these IDs

state
str (optional) Default: "any" 

restrict projects to just those with this state (one of `“live”, “closed”, or “any”)

start
date (optional) Example: YYYY-MM-DD

restrict warnings counts to include only those occurring on/after this date (in ISO 8601 format)

end
date (optional) Example: YYYY-MM-DD

restrict warnings counts to include only those occurring on/before this date

Crosstab Report Preferences

Get Crosstab Preferences
GET/api/v1/rh/companies/{company}/crosstabreportdefaults

Retrieves company Crosstab Report Preference configuration file.

Example URI

GET release.decipherinc.com/api/v1/rh/companies/company/crosstabreportdefaults
URI Parameters
HideShow
company
string (required) 

company ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "singleSelectOneD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "mean"
    ]
  },
  "singleSelectMultiD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "mean"
    ],
    "showGridTable": true,
    "showAllTables": true,
    "addRowSummaryTable": true
  },
  "multiSelectOneD": {
    "customBase": "shown",
    "expandable": true,
    "questionTableChartType": "column",
    "transpose": true,
    "stats": [
      "counts"
    ]
  },
  "numberOneD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "mean",
      "median",
      "stddev",
      "se",
      "sum",
      "min",
      "max"
    ]
  },
  "numberMultiD": {
    "customBase": "answering",
    "expandable": true,
    "summary": [
      "mean",
      "median",
      "stddev",
      "se",
      "sum",
      "min",
      "max"
    ],
    "stats": [
      "mean",
      "median",
      "stddev",
      "se",
      "sum",
      "min",
      "max"
    ]
  },
  "multiSelectMultiD": {
    "customBase": "shown",
    "expandable": true,
    "addRowSummaryTable": true,
    "stats": [
      "counts"
    ],
    "showGridTable": true,
    "showAllTables": true,
    "chartTypeMapping": {
      "gridTable": "column",
      "rowTable": "line",
      "counts": "bar"
    },
    "transpose": [
      "gridTable",
      "counts"
    ]
  },
  "ratingMultiD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "mean"
    ],
    "showGridTable": true,
    "showAllTables": false,
    "addRowSummaryTable": true
  },
  "ratingOneD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "se",
      "mean",
      "median"
    ],
    "summary": [
      "se",
      "mean",
      "median"
    ]
  }
}

Update Crosstab Preferences
PUT/api/v1/rh/companies/{company}/crosstabreportdefaults

Update a company Crosstab Reports Preference configuration file. Only parameters being updated need to be included.

Example URI

PUT release.decipherinc.com/api/v1/rh/companies/company/crosstabreportdefaults
URI Parameters
HideShow
company
string (required) 

company ID

configs
object (required) 

Crosstab Report Preferences

  • singleSelectOneD object (optional) Report Defaults for single select (radio/select) one dimensional question.

    • customBase string (optional) Sets the default % Base. Available values are answering, shown, segment.
    • expandable bool (optional) Sets the default choice for ‘Nest Rows Under Nets’.
    • stats array (optional) Sets default stats. Available values are mean, median, stddev, se.
    • transpose bool (optional) Sets default choice for transposing of question table.
    • questionTableChartType string (optional) Sets defaults choice for chart type. Available values are bar, column, pie, area, line.

  • singleSelectMultiD object (optional) Report Defaults for single select (radio/select) multi-dimensional question.

    • customBase string (optional) Sets the default % Base. Available values are answering, shown, segment.
    • expandable bool (optional) Sets the default choice for ‘Nest Rows Under Nets’
    • stats array (optional) Sets default stats. Available values are mean, median, stddev, se, sum, min, max.
    • summary array (optional) Sets default summary tables. Available values are mean, median, stddev, se, sum, min, max.
    • showGridTable bool (optional) Sets the default choice to display a grid table.
    • showAllTables bool (optional) Sets the default choice to display all tables.
    • transpose array (optional) Sets defaults choice for transposing of grid, main and stats summary tables. Available values are gridTable, rowTable, mean, median, stddev, se, sum, min, max.
    • addRowSummaryTable bool (optional) Sets the default choice to add a summary table for newly added rows (nets).
    • chartTypeMapping object (optional) Sets charts for grid, main or stat tables. See values of transpose for object key and values of questionTableChartType for value mapping.

  • multiSelectOneD object (optional) Report Defaults for multiselect (checkbox) one dimensional question.

    • customBase string (optional) Sets the default % Base. Available values are answering, shown, segment, responses.
    • expandable bool (optional) Sets the default choice for ‘Nest Rows Under Nets’.
    • stats array (optional) Sets default stats. Available value counts.
    • transpose bool (optional) Sets defaults choice for transposing of question table.
    • questionTableChartType string (optional) Sets defaults choice for chart type. Available values are bar, column, area, line.

  • multiSelectMultiD object (optional) Report Defaults for multi-select (checkbox) two dimensional question.

    • customBase string (optional) Sets the default % Base. Available values are answering, shown, segment, responses
    • expandable bool (optional) Sets the default choice for ‘Nest Rows Under Nets’
    • stats array (optional) Sets default stats. Available value counts.
    • summary array (optional) Sets default summary tables. Available value counts.
    • showGridTable bool (optional) Sets the default choice to display a grid table.
    • showAllTables bool (optional) Sets the default choice to display all tables.
    • transpose array (optional) Sets defaults choice for transposing of grid, main and stats summary tables. Available values are gridTable, rowTable, counts.
    • addRowSummaryTable bool (optional) Sets the default choice to add summary table for newly added rows(nets).
    • chartTypeMapping object (optional) Sets charts for grid, main or stat tables. See values of transpose for object key and values of questionTableChartType for value mapping.

  • numberOneD object (optional) Report Defaults for one dimensional numeric question.

    • customBase string (optional) Sets the default % Base. Available values are answering, shown, segment.
    • expandable bool (optional) Sets the default choice for ‘Nest Rows Under Nets’.
    • stats array (optional) Sets default stats. Available values are mean,median,stddev,se,sum,min,max.
    • transpose bool (optional) Sets defaults choice for transposing of question table.

  • numberMultiD object (optional) Report Defaults for two dimensional numeric question.

    • customBase string (optional) Sets the default % Base. Available values are answering, shown, segment.
    • expandable bool (optional) Sets the default choice for ‘Nest Rows Under Nets’.
    • stats array (optional) Sets default stats. Available values are mean,median,stddev,se,sum,min,max.
    • summary array (optional) Sets default summary tables. Available values are mean, median,stddev,se,sum,min,max.
    • transpose array (optional) Sets defaults choice for transposing of grid, main, and stats summary tables. Available values are gridTable, rowTable, mean,median,stddev,se,sum,min,max.
    • chartTypeMapping object (optional) Sets charts for main or stat tables. See values of transpose for object key and values of questionTableChartType for value mapping.

  • ratingOneD object (optional) Report Defaults for Rating one dimensional question.

    • customBase string (optional) Sets the default % Base. Available values are answering, shown, segment.
    • expandable bool (optional) Sets the default choice for ‘Nest Rows Under Nets’.
    • stats array (optional) Sets default stats. Available values are mean,median,stddev,se,sum,min,max.
    • transpose bool (optional) Sets defaults choice for transposing of question table.
    • questionTableChartType string (optional) Sets defaults choice for chart type. Available values are bar, column, pie, area, line.

  • ratingMultiD object (optional) Report Defaults for Rating multi-dimensional question.

    • customBase string (optional) Sets the default % Base. Available values are answering, shown, segment.
    • expandable bool (optional) Sets the default choice for ‘Nest Rows Under Nets’.
    • stats array (optional) Sets default stats. Available values are mean,median,stddev,se,sum,min,max.
    • summary array (optional) Sets default summary tables. Available values are mean,median,stddev,se,sum,min,max.
    • showGridTable bool (optional) Sets the default choice to display a grid table.
    • showAllTables bool (optional) Sets the default choice to display all tables.
    • addRowSummaryTable bool (optional) Sets the default choice to add summary table for newly added rows (nets).
    • transpose array (optional) Sets defaults choice for transposing of question grid, main or stat summary tables. Available values can be [gridTable, rowTable, mean,median,stddev,se,sum,min,max.
    • chartTypeMapping object (optional) Sets charts for grid, main or stat tables. See values of transpose for object key and values of questionTableChartType for value mapping.
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "singleSelectOneD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "mean"
    ]
  },
  "singleSelectMultiD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "counts"
    ],
    "showGridTable": true,
    "showAllTables": true,
    "addRowSummaryTable": true
  },
  "multiSelectOneD": {
    "customBase": "shown",
    "expandable": true,
    "questionTableChartType": "column",
    "transpose": true,
    "stats": [
      "counts"
    ]
  },
  "numberOneD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "mean",
      "median",
      "stddev",
      "se",
      "sum",
      "min",
      "max"
    ]
  },
  "numberMultiD": {
    "customBase": "answering",
    "expandable": true,
    "summary": [
      "mean",
      "median",
      "stddev",
      "se",
      "sum",
      "min",
      "max"
    ],
    "stats": [
      "mean",
      "median",
      "stddev",
      "se",
      "sum",
      "min",
      "max"
    ]
  },
  "multiSelectMultiD": {
    "customBase": "shown",
    "expandable": true,
    "addRowSummaryTable": true,
    "stats": [
      "counts"
    ],
    "showGridTable": true,
    "showAllTables": true,
    "chartTypeMapping": {
      "gridTable": "column",
      "rowTable": "line",
      "counts": "bar"
    },
    "transpose": [
      "gridTable",
      "counts"
    ]
  },
  "ratingMultiD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "mean"
    ],
    "showGridTable": true,
    "showAllTables": false,
    "addRowSummaryTable": true
  },
  "ratingOneD": {
    "customBase": "shown",
    "expandable": true,
    "stats": [
      "se",
      "mean",
      "median"
    ],
    "summary": [
      "se",
      "mean",
      "median"
    ]
  }
}

API key provisioning

While active, each API key can be used to perform any API call with the permissions of the user. The API keys are 64 character long: the first 32 characters are “public” and visible on your account page. The last 32 characters are secret visible only once, when the key is created; if you lose this information you will need to use the rekey action to reset the secret part and re-enter the API key.

Resource properties:

  • key the 32-character public part of the API key

  • user_id the user ID

  • user_email the email of the user (if non-shared)

  • user_name the username (if shared), e.g. “apitest”

  • user_fullname the human name of the user, e.g. “Bob Bobson”

  • restrictions is this key restricted to only certain API calls? Please see the Security section for more information.

  • active (boolean): false for keys that were active once but are now retired

  • calls (int): number of API calls this month

  • resource: resource usage this month

  • secret: the 32-character secret part of the key is visible only when creating or rekeying. While the key is the “username”, this is the password.

  • combined_key: for your convenient, this is the key + secret and what you should submit as x-apikey.

List API Keys
GET/api/v1/rh/apikeys

What API keys have been created?

A supervisor user will be able to see all API keys for his company. A staff user will be able to see all global API keys. Other user types will see only their own keys.

Example URI

GET release.decipherinc.com/api/v1/rh/apikeys
URI Parameters
HideShow
company
int (optional) 

Restrict array of keys keyed to users in this company ID

user
string (optional) 

Restrict array of keys to only this specific user. A user can be specified as a numeric ID, email address or shared user name. The special name “self” references to the owner of the API key.

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
 {
  "active": true,
  "restrictions": {},
  "user_id": 104,
  "user_email" : "john.doe@decipherinc.com",
  "user_fullname" : "John Q. Doe",
  "user_name" : null,
  "key": "1234567890abcdef1234567890abcdef",
  "resource": 69778,
  "calls": 63,
 }
]

Create API Key
POST/api/v1/rh/apikeys

Add a new API key.

Example URI

POST release.decipherinc.com/api/v1/rh/apikeys
URI Parameters
HideShow
user
string (required) 

user account that will be used when doing API calls with this key. Specific a numeric user ID, email address, shared user name or “self” for your own account

restrictions
object (optional) 

security restrictions for how the new key can be used

Request
HideShow
Body
{
  "user": "self"
}
Response  200
HideShow
Body
{
  "active": true,
  "restrictions": {},
  "user_id": 104,
  "id" : 1,
  "user_email" : "john.doe@decipherinc.com",
  "user_fullname" : "John Q. Doe",
  "user_name" : null,
  "key": "1234567890abcdef1234567890abcdef",
  "secret": "u6mfsvuqrdezyn5xayqrndcp7db7wrkt",
  "combined_key": "1234567890abcdef1234567890abcdefu6mfsvuqrdezyn5xayqrndcp7db7wrkt",
  "resource": 0,
  "calls": 0,
 }

Managing individual keys

Retire
DELETE/api/v1/rh/apikeys/{apikey}

Deactivate an API key. Keys that were created and never used are deleted; others are marked as inactive for audit purposes. The deleted value in the response will tell you whether the key was completely erased or just inactivated.

Example URI

DELETE release.decipherinc.com/api/v1/rh/apikeys/apikey
URI Parameters
HideShow
apikey
string (required) 

The API key to manipulate

Response  200
HideShow
Body
{deleted: true}

Update
PUT/api/v1/rh/apikeys/{apikey}

Change an API key’s restrictions. In the request body, specify an object with “restrictions” being the only valid key. The value of restrictions must follow the key restriction specification.

Example URI

PUT release.decipherinc.com/api/v1/rh/apikeys/apikey
URI Parameters
HideShow
apikey
string (required) 

The API key to manipulate

restrictions
object (required) 

updated restrictions for this key; set to {} for no restrictions

Request
HideShow
Body
{
  "restrictions": {
    "networks": [
      "8.8.8.8"
    ]
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "active": true,
  "restrictions" : {"networks" : ["8.8.8.8"] }
  "user_id": 104,
  "id" : 1,
  "user_email" : "john.doe@decipherinc.com",
  "user_fullname" : "John Q. Doe",
  "user_name" : null,
  "key": "1234567890abcdef1234567890abcdef",
  "resource": 0,
  "calls": 0,
 }

Get
GET/api/v1/rh/apikeys/{apikey}

Retrieve information about a single API key.

Example URI

GET release.decipherinc.com/api/v1/rh/apikeys/apikey
URI Parameters
HideShow
apikey
string (required) 

The API key to manipulate

Rekey
POST/api/v1/rh/apikeys/{apikey}

This allows for re-generation of the secret part of the API key while retaining restrictions and API key usage history.

Python library NOTE: As a convenience, the Python library allows you to run api.rekey() to call this function and immediately update the configuration file with the new key. You can also run beacon rekey from the command line to do the same.

Example URI

POST release.decipherinc.com/api/v1/rh/apikeys/apikey
URI Parameters
HideShow
apikey
string (required) 

The API key to manipulate

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "active": true,
  "restrictions" : {"networks" : ["8.8.8.8"] }
  "user_id": 104,
  "id" : 1,
  "user_email" : "john.doe@decipherinc.com",
  "user_fullname" : "John Q. Doe",
  "user_name" : null,
  "key": "1234567890abcdef1234567890abcdef",
  "secret": "u6mfsvuqrdezyn5xayqrndcp7db7wrkt",
  "resource": 0,
  "calls": 0,
 }

Archive Project

Archives project and deletes the project directory. Data retention rules will be followed unless force parameter is used.

Archive Project
POST/api/v1/surveys/{survey}/archive

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/archive
URI Parameters
HideShow
survey
string (required) 

survey path to be archived. You must have survey edit permissions.

force
bool (optional) Default: false 

Allows archiving projects when the required time before archival has not been met. Live projects or project directories with keep flag will not be archived.

subdirectories
bool (optional) Default: false 

Allows archival of project folder and all its sub-directories (surveys). Ensure these sub-directories are not being accessed by other projects (dashboards or reports) before using this parameter.

Un-archive Project

Un-archive Project
POST/api/v1/surveys/{survey}/unarchive

Un-archives project to {survey} directory.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/unarchive
URI Parameters
HideShow
survey
string (required) 

survey path to be un-archived. You must have survey edit permissions.

Archived data management

Purge collected data in archive
DELETE/api/v1/archives

Modifies an already archived survey, removing all collected data from the archive and re-archiving it. This cannot be undone. Requires staff access.

Example URI

DELETE release.decipherinc.com/api/v1/archives
URI Parameters
HideShow
archived_path (string)... archived path, which is something like selfserve_53a_200001.tar.gz. These paths can be found using e.g. the "archived" command on the command line
string (required) 

Planned archival activities

Retrieve planned activities
GET/api/v1/archives/planned

Returns an array of objects, describing what surveys will be automatically archived (if enabled) and what archived surveys will have their collected data cleared (if enabled). Only projects that would be visible in the portal are returned.

List is sorted chronologically, with surveys set to be kept forever (date column blank) last. The days is the retention for clearing or archiving which can come from server or company configuration. action is either archive for surveys in the system that will move to the archive, or clear for surveys already archived which will have any respodnent data stripped at that time.

Example URI

GET release.decipherinc.com/api/v1/archives/planned
Response  200
HideShow
Headers
Content-Type: 200
Body
[
 {
  "date": "2021-03-19T23:16:53Z",
  "action": "clear",
  "path": "selfserve/93a/200412",
  "retention": 90,
  "title": "COVID-19 Study",
 },

  {
   "date": null,
   "action": "archive",
   "path": "selfserve/1fbc/sfc16004",
   "retention": 30,
   "title": "Product Preferences"
  }
 ]

Reporting

Crosstabs

Execute Custom
POST/api/v1/surveys/{survey}/crosstabs/execute

Allows you to execute a crosstabs run with custom segments and filters. This is exactly the same interface that the crosstabs user interface uses to get the data to display the tables.

The normal output is fairly complex: you may also request very simplified format by passing simplified set to true.

In the normal output, the object return has the following properties (note: values are strings unless explicitly mentioned):

  • segments – array of segment objects you have requested:

  • count – count of participants matching the segment.

  • abbr – label used for stat testing.

  • sg if is set and not null, this segment was stat tested against only other segments within the same sg value.

  • cond segment condition (Python expression ,e.g. “ALL” or “q1.r1”)

  • title segment’s title

  • objects – an array of the table data

  • dlident – the “DownLoad IDENT” value can be used to create a direct link to a report run or to download data matching the report segments.

The objects property contains an array of the table data. Each table is an object containing:

  • label the table label. This uniquely identifies a table. The table label consists of the question’s system label (i.e. label as specified in the XML file, and not through e.g. variables.xls or data export customization), a $ sign then a sub-label. For example, if question q1 has only one table it will be labelled q1$. Multiple tables might be labelled q1$r1 and q1$mean (for Mean Summary table).

  • qlabel the label of the underlying question

  • title the main title of this table. This will be the question’s title

  • subtitle when a question has multiple tables, each will have a different subtitle. May be null if no subtitle

  • rows an array of objects defining the table row structures

  • data an 3D array with data for this table, indexed by row index, segment index and data value

  • qtype question type of the underlying question (corresponds to the lower-case XML tag, e.g. “radio”)

  • segments segments that were applied to this particular table. When using pinned reports, tables display may have non-uniform segments

  • qa an array of QA codes for the underlying question. Each array element is a 2-element array of the QA code (e.g. SHF(r)) and the human readable explanation (e.g. “Rows are shuffled”)

  • intent This is null for all tables except net summaries, where it’s summary

  • obj the XML object that is the primary object driving this table. For a question that generates a single table, this will be e.g. “q1”. For question that consists of multiple tables (e.g. 2D radio grouped by rows), “q1,r1” … “q1,r5”.

  • tableType Set to simple (table contains percentages), numeric (table contains stats such as mean), net" (additional table created for variable nets) or stat (summary table for stats)

The rows array contains one row object for each visible row with the following properties:

  • obj the underlying object for the row (e.g. “q1,c1” would mean the row was created from the definition of column “c1” within question “q1”)

  • title the reporting title to be displayed for the row (the reporting title starts out as what is specified in the survey.xml with HTML etc. stripped; it can be customized in the report)

  • label the row label. This is typically the label of the underlying row or column, e.g. “c1”

  • cond the Python logic condition that was used to generate the data for the table row

  • dv the data value used for statistical calculation (e.g. if showing a rating question table with 5 rows, the data values might span from 5 to 1 or 1 to 5 depending on whether the scale is ascending or descending)

  • intent Set to total for the total row, data for ordinary data rows showing a percentage, numnet for numeric nets, net for normal nets and stat for statistic rows

  • stat If intent=“stat”, this describes what stat is being shown in this row. One of counts (checkbox count), mean, stddev, median, se (Standard Error) or sum.

  • qa optional property: if it exists it’s an array of QA codes specific to the underlying survey row or column

  • pct hint on how to display percentages. If null then percentages should not be disabled for this table row. This value is set on rows that are not included in the total base (I.e. “Refuse to Answer”) which in the survey.xml are configured as aggregates="0".

The data array contains one entry per item in the rows. Each entry in data is another array, containing one item per segment in this table. That final item is an array again with two possible layouts. If the row’s intent is stat then this is a statistical row with 3 items:

  • 0 the stat value (mean, median etc. depending on the stat property of the matching row)

  • 1 the count of items matching the condition

  • 2 stat testing data (see below).

If intent is set to anything but stat the row is a percentage row, i.e. displaying a count and percentages. It will have 5 items:

  • 0 vertical percentage, relative to the effective base for this row. This percentage is emitted with 6 digits of precision

  • 1 weighted count (rounded to nearest number)

  • 2 unweighted count. This will be the same as item #1 unless weighting was applied

  • 3 effective base. This is used for stat testing calculations and will be slightly different from normal base if weighting was used.

  • 4 stat testing data. Either null or an array containing references to other columns where a stat test was successful. The reference is either the upper or lower-case variant of the row’s abbr property.

If you specify simplified = true, the output is vastly simplified. It will be an object with one property by table label, for example q1$r1. The value is an array of the rows displayed: the first element is the row’s title and the next N*2 elements are the percentage or stat value and count, one per segment

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/crosstabs/execute
URI Parameters
HideShow
survey
string (required) 

survey path to run crosstabs in

simplified
bool (optional) Default: false 

generate vastly simplified output rather than the full

segments
array (optional) Default: [{"title" :"All", cond:"ALL"}] 

an array of segment objects to split all the tables by. Each segment object should contain the properties title, cond and may optionally contain sg to create custom stat test groups. If you do not specify a title, one is attempted derived from cond (this is possible only for simple conditions like “q1.r1”).

filters
array (optional) Default: ["qualified"] 

an array of Python conditions to apply. These filter conditions are applied before any segments.

base
string (optional) Default: "answering" 

how should percentages be calculated?

  • answering: percentages are based on those answering the question.

  • segment: the total in the segment is used.

  • shown: percentages shown but not necessarily answering the question.

  • variable: percentage shown the variable (for checkbox variables only; you must have trackVars="checkbox" configured)

tables
array (optional) Example: ["q1$", "q2$r1", "q2$R3"]

show only tables with these table labels.

aggregates
bool (optional) Default: true 

show output matching report grid tables. If set to false, question tables are not aggregated and a separate table is shown for each data variable. Not Applicable for saved reports.

Crosstabs configuration

Get Crosstab Configuration
GET/api/v1/surveys/{survey}/crosstabs/configuration

Retrieves segments and globally available weighting variables configured for a survey.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/crosstabs/configuration
URI Parameters
HideShow
survey
string (required) 

survey path

Crosstabs table settings

Delete Crosstab Settings
DELETE/api/v1/surveys/{survey}/crosstabs/tablesettings

Reset all tables to their “as programmed” state, removing any customization. Requires reporting: edit permission for the project.

Example URI

DELETE release.decipherinc.com/api/v1/surveys/survey/crosstabs/tablesettings
URI Parameters
HideShow
survey
string (required) 

survey path

tablename
string (required) 

table to reset

Saved Reports

List reports
GET/api/v1/surveys/{survey}/crosstabs/saved

Lists “saved reports” and “saved crosstabs” created on a survey. For each report, following information is returned:

  • id: the unique ID of the report; use it to execute it

  • title: the title

  • description: the full description

  • visibility: (deprecated) one of public (anyone – even without login – can view), protected (only owner can edit), or shared (anyone with survey access can edit)

  • access: one of public (anyone – even without login – can view), private (only owner can view/edit), or readonly (anyone with survey access can view)

  • updated_on: (datetime) when was this report last changed

  • created_on: (datetime) when was this report created

  • updated_by: (user id) who modified this report last

  • tmp: (bool) indicates if this report has been saved

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/crosstabs/saved
URI Parameters
HideShow
survey
string (required) 

the survey to list saved reports for

Execution

Execute
POST/api/v1/surveys/{survey}/crosstabs/saved/{saved}/execute

This runs the saved report/crosstab, outputting the same format as an ordinary crosstab.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/crosstabs/saved/1h7c1s5znuk1/execute
URI Parameters
HideShow
survey
string (required) 

survey path to run crosstabs in

saved
string (required) Example: 1h7c1s5znuk1

the 12 or 16 character report ID

simplified
bool (optional) Default: false 

generate vastly simplified output rather than the full

aggregates
bool (optional) Default: true 

show output matching report grid tables. If set to false, question tables are not aggregated and a separate table is shown for each data variable. Not Applicable for saved reports.

Exports

Export
POST/api/v1/surveys/{survey}/crosstabs/saved/{saved}/export/{format}

Request a conversion of saved report. The request file type is immediately returned.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/crosstabs/saved/1h7c1s5znuk1/export/format
URI Parameters
HideShow
survey
string (required) 

the survey whose saved report you want to execute

saved
string (required) Example: 1h7c1s5znuk1

the 12 or 16 character report ID

format
string (required) 

one of “pptx” (Microsoft PowerPoint), “excel” (Excel) or “pdf” (Adobe PDF)

aggregates
bool (optional) Default: true 

show output matching report grid tables. If set to false, question tables are not aggregated and a separate table is shown for each data variable. Not Applicable for saved reports.

RIM weighting

Update Rim Weighting
PUT/api/v1/surveys/{survey}/crosstabs/weighting/rim/{var}

Create per-record weights based on a set of RIM variables and breaks. The algorithm as described in the Wincross manual is used.

Returns an array, one object per input chunk:

  • success: true if we managed to hit convergence within the required number of iterations

  • rms: root mean square of last iteration, which is compared to the desired convergence

  • debug: textual debug information about what happened in each iteration

  • efficiency: efficiency factor of generated weights

  • wprop: achieved weights per break in each variable

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/crosstabs/weighting/rim/var
URI Parameters
HideShow
survey
string (required) 

survey path to run crosstabs in

var
string (required) 

the target var to save the data in. This will be created as a new or updated column in the nweight.txt file

iterations
int (required) Default: 50 

how many times should we try to approximate the variables

minWeight
float (required) Default: 0.0001 

minimum acceptable record weight

maxWeight
float (required) Default: inf 

maximum acceptable record weight (by default, no limit)

converge
float (required) Default: 0.000005 

acceptable convergence to consider the test done before completing all iterations

test
boolean (required) Default: false 

in test mode, do not save the data but still run the calculations

chunks
array (required) 

an array of objects, containing precondition and variables. Each variable is an array for each variable (e.g. Gender) to test containing an array of objects that are values. Each value is a crosstabs condition and the desired percentage ratio (must add up to 100%).

Logic Validation

Validate Logic
GET/api/v1/surveys/{survey}/crosstabs/validate

Check whether the logic is valid for crosstabs.

Returns an empty object if valid or an error string if invalid:

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/crosstabs/validate
URI Parameters
HideShow
survey
string (required) 

survey path to run crosstabs in

logic
string (required) 

the quoted logic to be tested

Nets

Create or Update Net
PUT/api/v1/surveys/{survey}/crosstabs/nets

Create or overwrite all nets on a table, or update the nest setting on existing nets.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/crosstabs/nets
URI Parameters
HideShow
survey
string (required) 

survey path to run crosstabs in

tables
array (required) 

an array of the tables and their updated nets. Each table is an object with:

  • table string (required) The label of the target question

  • nest boolean (optional) When set to True the net rows will appear nested under the nets in the crosstab tables

  • nets array (optional) an array of the new nets. Each net is an object with

    • label string (optional) A label used to identify a net so that it may be included in the items of another net
    • summary boolean (optional) Adds a summary table for the net (multidimensional questions only)
    • title string (required) The title to be shown in the crosstabs table for the net
    • items array (required) An array of the question’s row labels to be included in this net
    • op string (required) The operation of the net. May be one of the following:
      • or – generates an “OR” net
      • and – generates an “AND” net
      • count – generates a “Count” net
      • mean – generates a “Mean” net
      • median – generate a “Median” net
      • max – generate a “Maximum” net
      • min – generate a “Minimum” net
      • sum – generate a “Sum” net
      • se – generate a “Standard Error” net
      • stddev – generate a “Standard Deviation” net
Request
HideShow
Body
PUT /api/v1surveys/{survey}/crosstabs/nets tables='[{"table": "q1"...}]'
Request  new nets
HideShow

Providing a nets key in the table will trigger an overwrite of all existing nets in the table.

Body
[
  {
    "table": "q1",
    "nest": true,
    "nets": [
      {
        "title": "1 or 2",
        "op": "or",
        "items": [
          "r1",
          "r2"
        ],
        "summary": false
      },
      {
        "title": "3 and 4",
        "op": "and",
        "items": [
          "r3",
          "r4"
        ]
      }
    ]
  },
  {
    "table": "q2"
  }
]
Request  nested nets
HideShow

A nested net requires defining sub net first with a unique label added in items in parent net.

Body
[
  {
    "table": "q1",
    "nest": true,
    "nets": [
      {
        "label": "subnet",
        "title": "subnet for 1 or 2",
        "op": "or",
        "items": [
          "r1",
          "r2"
        ]
      },
      {
        "title": "parent net",
        "op": "or",
        "items": [
          "subnet",
          "r3"
        ]
      }
    ]
  }
]
Request  toggle nesting
HideShow

To update only the ‘Nest Rows under Nets’ setting without overwriting existing nets:

Body
[
  {
    "table": "q1",
    "nest": true
  }
]

Response Summary

Response Summary API

Quota Settings

Requires dashboard.view permissions.

Set Quota Settings
PUT/api/v1/surveys/{survey}/summary/quota_settings

Set survey quota settings for hide/display In-progress, Overquota, and Quota definition(tooltip)

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/summary/quota_settings
URI Parameters
HideShow
survey
string (required) 

Path to your survey

showInProgress
boolean (required) 

True to show, False to hide in progress quota

showOverQuota
boolean (required) 

True to show, False to hide in over quota

showTooltips
boolean (required) 

True to show, False to hide tooltip

Request
HideShow
Body
{
  "showInProgress": true,
  "showOverQuota": true,
  "showTooltips": false
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Toggle Survey Table

Requires dashboard.edit permissions.

Set Table
PUT/api/v1/surveys/{survey}/summary/set_table_toggle

Toggle survey table in quota sheet

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/summary/set_table_toggle
URI Parameters
HideShow
survey
string (required) 

Path to your survey

Request
HideShow
Body
{}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Sample Management

Bounce-Backs

Bounced
POST/api/v1/bulk/bounced

Send a list of emails to check for known bounce-backs. Staff access required.

Example URI

POST release.decipherinc.com/api/v1/bulk/bounced
URI Parameters
HideShow
emails
array (required) 

list of email addresses to check.

Response  200
HideShow
Headers
Content-Type: 200
Body
{
  "misses": 0,
  "bounced": [
    {
      "reason": "Mailbox unavailable",
      "code": "550",
      "email": "baduser@badaddress.com",
      "tstamp": "2016-05-02T19:19:27Z"
    }
  ],
  "hits": 1
}

Web Intercepts

You must have at least dashboard view permissions to access this endpoint.

The webconf_id used in the below endpoints is the part of the webconf filename after the dash (and before the extension) (i.e., webconf-<webconf_id>.js)

Get Tags
GET/api/v1/surveys/{survey}/webconfs/{webconf_id}/tags

Get all tags from a web config. Each tag consists of the following required properties as well as any custom parameters defined by the config.

  • id (str): tag ID

  • enabled (bool): true if the tag is enabled (requires code to utilize the parameter)

  • title (str): title of the tag

  • survey_url (str): survey URL

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/webconfs/webconf_id/tags
URI Parameters
HideShow
survey
string (required) 

survey path

webconf_id
string (required) 

webconf ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
[{
"id": "abc12",
"title": "Home Page",
"enabled": true,
"survey_url": "https://selfserve.decipherinc.com/survey/selfserve/53a/1234",
"rate": 5,
"delay": 10
}, {
"id": "abc13",
"title": "Help Page",
"enabled": False,
"survey_url": "https://selfserve.decipherinc.com/survey/selfserve/53a/1234",
"rate": 20,
"delay": 60
}]

Create Tag
POST/api/v1/surveys/{survey}/webconfs/{webconf_id}/tags

Add a tag to the web config. Default values are applied for any omitted parameters.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/webconfs/webconf_id/tags
URI Parameters
HideShow
survey
string (required) 

survey path

webconf_id
string (required) 

webconf ID

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "tag": {
    "rate": 10
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "abc12"
}

Modifying Web Intercepts

Update Tag
PUT/api/v1/surveys/{survey}/webconfs/{webconf_id}/tags/{tag_id}

Update a web config tag. Only parameters being updated need to be included.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/webconfs/webconf_id/tags/tag_id
URI Parameters
HideShow
survey
string (required) 

survey path

webconf_id
string (required) 

webconf ID

tag_id
string (required) 

tag ID

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "tag": {
    "rate": 20
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Deleting Web Intercepts

Delete Tag
DELETE/api/v1/surveys/{survey}/webconfs/{webconf_id}/tags/{tag_id}

Delete a web config tag.

Example URI

DELETE release.decipherinc.com/api/v1/surveys/survey/webconfs/webconf_id/tags/tag_id
URI Parameters
HideShow
survey
string (required) 

survey path

webconf_id
string (required) 

webconf ID

tag_id
string (required) 

tag ID

Request
HideShow
Headers
Content-Type: application/json
Body
{}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Web Intercept Cache

Purge Tag Cache
POST/api/v1/surveys/{survey}/webconfs/{webconf_id}/cache/invalidate

Purge the CDN’s cache of a web config.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/webconfs/webconf_id/cache/invalidate
URI Parameters
HideShow
survey
string (required) 

survey path

webconf_id
string (required) 

webconf ID

Request
HideShow
Body
{}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Distribution

You can receive any data as a response to your API. However what if you want to send someone an email with a PDF report? We provide a number of generic “meta-APIs” where you can take output of any API call and send it as an attachment via email or other means.

Email

Send API to Email
POST/api/v1/distribute/email

This meta-API call requires you to specify another API call as input, although you can also omit the sub-calls and send an email with subject and body of your choosing.

You can specify any amount of API calls that generate attachments (i.e. non-JSON output). Currently (Decipher 26) the useful calls are:

Acceptable Use Policy: all recipients must have given opt-in to receive the emails you sent. You may contact solely your business associates, i.e. not invite survey participants.

Color Theme support: these color names can be overridden by passing in the name and new value as colors.

  • linkTextColor = “#E15603”

  • emailBackgroundColor = "#2A4068,

  • emailForegroundColor = “#FFFFFF”

  • emailContentAlignment = “center”,

  • emailPageColor = “#FFFFFF”

  • linkButtonColor = “#5B9FFF”

  • linkButtonTextColor = “#EDF8FF”

  • defaultTextColor = “#333”

Example URI

POST release.decipherinc.com/api/v1/distribute/email
URI Parameters
HideShow
sources
array (required) 

any number of API data sources to call to get the data. Each data source is an object containing the key property with the name of the API to call, e.g. /api/v1/surveys/your/survey/datamap. You may also specify an args property which is an object with additional argument. Note that URL arguments must be passed via args only. You may also specify method if the API call is to not use “GET”.

recipients
array (required) 

list of email addresses to send this to

subject
array (required) 

the subject of the email that will be sent out

sender
string (required) 

the name that will apper as sender. Defaults to the full name of the account behind the API key

body
string (optional) 

message to put in the body. HTML capable.

colors
object (optional) 

set of colors to override the default email template.

Request
HideShow
Body
{
  "body": "This is your daily data file upload. Attached you will find the datamap and a data file of all group 4 participants.",
  "sources": [
    {
      "api": "/api/v1/surveys/demo/report/tables/datamap",
      "method": "GET",
      "args": {
        "format": "html"
      }
    },
    {
      "api": "/api/v1/surveys/demo/report/tables/data",
      "method": "GET",
      "args": {
        "cond": "q1.r1",
        "format": "tab"
      }
    }
  ],
  "recipients": [
    "client_one@example.com",
    "client_two@example.com"
  ],
  "subject": "Your Daily Datamap and data file"
}
Response  200
HideShow
Headers
Content-Type: 200
Body
{}

SFTP

Send API to SFTP
POST/api/v1/distribute/ftp

Upload data via FTP or SFTP. This meta-API call requires you to specify another API call as input

You can specify any amount of API calls that generate attachments (i.e. non-JSON output). Currently (Decipher 26) the useful calls are:

If successful, a log of the connection is returned.

Example URI

POST release.decipherinc.com/api/v1/distribute/ftp
URI Parameters
HideShow
sources
array (required) 

any number of API data sources to call to get the data. Each data source is an object containing the key property with the name of the API to call, e.g. /api/v1/surveys/your/survey/datamap. You may also specify an args property which is an object with additional argument. Note that URL arguments must be passed via args only. You may also specify method if the API call is to not use “GET”. Specify filename to set a filename to be uploaded

username
string (required) 

user name to login with

password
string (required) 

password for the user

host
string (required) Example: ftp.client.com

remote hostname.

protocol
string (required) Default: sftp 

either ftp or sftp. SFTP is “FTP” over SSH and is the only recommended transfer method

directory
string (required) 

switch to this directory before uploading the files.

Request
HideShow
Body
{
  "username": "anonymous2",
  "protocol": "ftp",
  "sources": [
    {
      "api": "/api/v1/surveys/demo/kitchensink/data",
      "method": "GET",
      "args": {
        "format": "tab"
      }
    }
  ],
  "host": "localhost",
  "directory": "upload",
  "password": "whatever@domain.com"
}
Response  200
HideShow
Headers
Content-Type: 200
Body
{
  "debug": "[28/Jul/15 20:31:58] 220 (vsFTPd 2.3.5)\n[28/Jul/15 20:31:58] 220 (vsFTPd 2.3.5)\n[28/Jul/15 20:31:58] 230 Login successful.\n[28/Jul/15 20:31:58] 250 Directory successfully changed.\n[28/Jul/15 20:31:58] 226 Transfer complete.\n[28/Jul/15 20:31:58] /home/bgates/Private/h/dev/data/tmp/tmpCEi7Qf transferred to localhost\n"
}

Slack

Send API to Slack
POST/api/v1/distribute/slack

Send a message to a Slack channel or user. Together with hooks this can be used to notify users of certain happenings in their surveys or systems. Visit https://api.slack.com/ to receive an integration token you can immediately use below. The message will be sent from the user BeaconBot (username).

Example URI

POST release.decipherinc.com/api/v1/distribute/slack
URI Parameters
HideShow
company
string (required) 

your company ID at Slack

token
string (required) 

the API token Slack has given you

text
string (required) 

text to post

target
string (required) 

Either a #channelname or @user for a private message.

Survey test URL

You must have survey edit permissions to access this endpoint.

Get survey test URL token
GET/api/v1/surveys/{survey}/test/token

Generates a temporary token to access surveys for testing purposes. Data won’t be collected

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/test/token
URI Parameters
HideShow
survey
string (required) 

path to survey

expires
integer (optional) Default: 7 

days to expire token

Request
HideShow
Body
{
  "expires": 7
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "token": "TOKEN",
  "url": "https://release.decipherinc.com/survey/selfserve/53a/1234?v2test=TOKEN"
}

Campaign Manager

Email Campaigns

Get Campaigns
GET/api/v1/surveys/{survey}/campaigns

Returns a list of basic information about the Campaign Manager campaigns associated with this survey.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns
URI Parameters
HideShow
survey
string (required) 

path to survey

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
 {
  "name": "Untitled Campaign",
  "replyTo": "invite@decipherinc.com",
  "fromName": "Sender",
  "listSize": 1,
  "date": "2017-11-20T20:13:28Z",
  "fromAddress": "invite@decipherinc.com",
  "id": 2080,
  "subject": "Subject",
  "requireSeed": true
 },
]

Create Campaign
POST/api/v1/surveys/{survey}/campaigns

Creates a new campaign for the given survey. Values may optionally be provided for name, replyTo, fromName, fromAddress, link, and/or subject if overriding the defaults is desired. See example request below for defaults. A campaign created through this endpoint allows sends to be scheduled while other sends are already scheduled.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/campaigns
URI Parameters
HideShow
survey
string (required) 

Path to survey

name
string (optional) 

Name of campaign

replyTo
string (optional) 

Reply-To email address to use when sending emails, must be a valid email address

fromName
string (optional) 

Sender name to use when sending emails

fromAddress
string (optional) 

Sender email address to use when sending emails, must be an email address that the user and project has permission to send emails from

link
string (optional) 

Survey link, must be a link to the appropriate survey

subject
string (optional) 

Subject to use when sending emails

requireSeed
boolean (optional) Default: True 

Requires the campaign to use seed sends. When False, the campaign cannot be edited or launched via Campaign Manager.

Request
HideShow
Body
{
  "name": "Untitled Campaign",
  "replyTo": "invite@companyemail.com",
  "fromName": "Sender",
  "link": "https://<server domain>/survey/selfserve/123/456001?source=[source]",
  "fromAddress": "invite@companyemail.com",
  "subject": "Subject",
  "requireSeed": true"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 232,
  "date": "2020-03-23T16:48:57Z",
  "listSize": null,
  "name": "Untitled Campaign",
  "replyTo": "invite@companyemail.com",
  "fromName": "Sender",
  "link": "https://<server domain>/survey/selfserve/123/456001?source=[source]",
  "fromAddress": "invite@companyemail.com",
  "subject": "Subject",
  "requireSeed": true"
}

Individual Campaigns

Get Campaign
GET/api/v1/surveys/{survey}/campaigns/{campaign}

Returns basic information about an individual campaign.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign
URI Parameters
HideShow
survey
string (required) 

Path to survey

campaign
integer (required) 

ID of the campaign

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 232,
  "date": "2020-03-23T16:48:57Z",
  "listSize": null,
  "name": "Untitled Campaign",
  "replyTo": "invite@companyemail.com",
  "fromName": "Sender",
  "link": "https://<server domain>/survey/selfserve/123/456001?source=[source]",
  "fromAddress": "invite@companyemail.com",
  "subject": "Subject",
  "requireSeed": true"
}

Edit Campaign
PUT/api/v1/surveys/{survey}/campaigns/{campaign}

Modifies either name, replyTo, fromName, fromAddress, link, subject, and/or requireSeed of an individual campaign.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign
URI Parameters
HideShow
survey
string (required) 

Path to survey

campaign
integer (required) 

ID of the campaign

name
string (optional) 

Name of campaign

replyTo
string (optional) 

Reply-To email address to use when sending emails, must be a valid email address

fromName
string (optional) 

Sender name to use when sending emails

fromAddress
string (optional) 

Sender email address to use when sending emails, must be an email address that the user and project has permission to send emails from

link
string (optional) 

Survey link, must be a link to the appropriate survey

subject
string (optional) 

Subject to use when sending emails

requireSeed
boolean (optional) 

Requires the campaign to use seed sends. Cannot be changed once a soft send is done.

Request
HideShow
Body
{
  "name": "Untitled Campaign",
  "replyTo": "invite@companyemail.com",
  "fromName": "Sender",
  "link": "https://<server domain>/survey/selfserve/123/456001?source=[source]",
  "fromAddress": "invite@companyemail.com",
  "subject": "Subject",
  "requireSeed": true"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 232,
  "date": "2020-03-23T16:48:57Z",
  "listSize": null,
  "name": "Untitled Campaign",
  "replyTo": "invite@companyemail.com",
  "fromName": "Sender",
  "link": "https://<server domain>/survey/selfserve/123/456001?source=[source]",
  "fromAddress": "invite@companyemail.com",
  "subject": "Subject",
  "requireSeed": true"
}

Campaign Email Invite

Get Invite
GET/api/v1/surveys/{survey}/campaigns/{campaign}/invite

Retrieve the content body of the email invite and of the reminder email.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/invite
URI Parameters
HideShow
survey
string (required) 

Path to survey.

campaign
int (required) 

ID of the campaign.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "content": "<div style=\"margin:0 auto;\">\n<div id=\"emailBody\" style=\"min-width: 240px; max-width: 780px; display: block; margin: 0 auto; padding: 20px;\">\n<p style=\"text-align: left;\">\nDear Sir or Madam,\n<br /><br />\nWe are conducting research on your usage of our products and services.  This is your chance to make a difference in the way we do business.  Please take a moment to fill out this short survey.   Your answers will only be used in aggregate, and no personal information will be shared independent of the aggregated results.  Please be honest, as we take your answers and suggestions to heart.\n<br /><br />\nClick below to get started:\n</p>\n<p style=\"text-align: center;\">\n<a href=\"[surveyLink]\">Take our survey</a><br/>\n</p>\n<p style=\"text-align: center;\">\nResearch By Example | 1234 N Main St. | Anytown, CA 22313\n</p>\n<p style=\"text-align: center;\">\n<span style=\"font-size: 11px;\">\nIf you no longer wish to receive these emails, you may unsubscribe by clicking <a\nhref=\"[optOutLink]\">here</a>.\n</span>\n</p>\n</div>\n</div>\n&nbsp; <br/>",
  "reminder": "<div style=\"margin:0 auto;\">\n<div id=\"emailBody\" style=\"min-width: 240px; max-width: 780px; display: block; margin: 0 auto; padding: 20px;\">\n<p style=\"text-align: left;\">\nDear Sir or Madam,\n<br /><br />\nWe are conducting research on your usage of our products and services.  This is your chance to make a difference in the way we do business.  Please take a moment to fill out this short survey.   Your answers will only be used in aggregate, and no personal information will be shared independent of the aggregated results.  Please be honest, as we take your answers and suggestions to heart.\n<br /><br />\nClick below to get started:\n</p>\n<p style=\"text-align: center;\">\n<a href=\"[surveyLink]\">Take our survey</a><br/>\n</p>\n<p style=\"text-align: center;\">\nResearch By Example | 1234 N Main St. | Anytown, CA 22313\n</p>\n<p style=\"text-align: center;\">\n<span style=\"font-size: 11px;\">\nIf you no longer wish to receive these emails, you may unsubscribe by clicking <a\nhref=\"[optOutLink]\">here</a>.\n</span>\n</p>\n</div>\n</div>\n&nbsp; <br/>",
  "subject": "Share your feedback",
  "reminder_subject": "Reminder -- Share your feedback",
  "fromName": "FocusVision",
  "reminder_fromName": "FocusVision",
  "fromAddress": "invite@decipherinc.com",
  "reminder_fromAddress": "invite@decipherinc.com",
  "replyTo": "invite@decipherinc.com",
  "reminder_replyTo": "invite@decipherinc.com"
}

Edit Invite
PUT/api/v1/surveys/{survey}/campaigns/{campaign}/invite

Update the content body of the email invite or of the reminder email. Note that the invite content that is used for any in-progress sends are not editable until the send is either cancelled or completed.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/invite
URI Parameters
HideShow
survey
string (required) 

Path to survey.

campaign
int (required) 

ID of the campaign.

content
string (optional) 

Content of the email to use for the email campaign.

reminder
string (optional) 

Content of the reminder email to use for any reminder email sends.

subject
string (optional) 

Subject line of the email

reminder_subject
string (optional) 

Subject line of the reminder email

fromName
string (optional) 

Sender name to use when sending emails

reminder_fromName
string (optional) 

Sender name to use when sending reminder emails

fromAddress
string (optional) 

Sender email address to use when sending emails, must be an email address that the user and project has permission to send emails from

reminder_fromAddress
string (optional) 

Sender email address to use when sending reminder emails, must be an email address that the user and project has permission to send emails from

replyTo
string (optional) 

Reply-To email address to use when sending emails, must be a valid email address

reminder_replyTo
string (optional) 

Reply-To email address to use when sending reminder emails, must be a valid email address

Request
HideShow
Body
{
  "content": "<div style=\"margin:0 auto;\">\n<div id=\"emailBody\" style=\"min-width: 240px; max-width: 780px; display: block; margin: 0 auto; padding: 20px;\">\n<p style=\"text-align: left;\">\nDear Sir or Madam,\n<br /><br />\nWe are conducting research on your usage of our products and services.  This is your chance to make a difference in the way we do business.  Please take a moment to fill out this short survey.   Your answers will only be used in aggregate, and no personal information will be shared independent of the aggregated results.  Please be honest, as we take your answers and suggestions to heart.\n<br /><br />\nClick below to get started:\n</p>\n<p style=\"text-align: center;\">\n<a href=\"[surveyLink]\">Take our survey</a><br/>\n</p>\n<p style=\"text-align: center;\">\nResearch By Example | 1234 N Main St. | Anytown, CA 22313\n</p>\n<p style=\"text-align: center;\">\n<span style=\"font-size: 11px;\">\nIf you no longer wish to receive these emails, you may unsubscribe by clicking <a\nhref=\"[optOutLink]\">here</a>.\n</span>\n</p>\n</div>\n</div>\n&nbsp; <br/>",
  "reminder": "<div style=\"margin:0 auto;\">\n<div id=\"emailBody\" style=\"min-width: 240px; max-width: 780px; display: block; margin: 0 auto; padding: 20px;\">\n<p style=\"text-align: left;\">\nDear Sir or Madam,\n<br /><br />\nWe are conducting research on your usage of our products and services.  This is your chance to make a difference in the way we do business.  Please take a moment to fill out this short survey.   Your answers will only be used in aggregate, and no personal information will be shared independent of the aggregated results.  Please be honest, as we take your answers and suggestions to heart.\n<br /><br />\nClick below to get started:\n</p>\n<p style=\"text-align: center;\">\n<a href=\"[surveyLink]\">Take our survey</a><br/>\n</p>\n<p style=\"text-align: center;\">\nResearch By Example | 1234 N Main St. | Anytown, CA 22313\n</p>\n<p style=\"text-align: center;\">\n<span style=\"font-size: 11px;\">\nIf you no longer wish to receive these emails, you may unsubscribe by clicking <a\nhref=\"[optOutLink]\">here</a>.\n</span>\n</p>\n</div>\n</div>\n&nbsp; <br/>",
  "subject": "Share your feedback",
  "reminder_subject": "Reminder -- Share your feedback",
  "fromName": "FocusVision",
  "reminder_fromName": "FocusVision",
  "fromAddress": "invite@decipherinc.com",
  "reminder_fromAddress": "invite@decipherinc.com",
  "replyTo": "invite@decipherinc.com",
  "reminder_replyTo": "invite@decipherinc.com"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "content": "<div style=\"margin:0 auto;\">\n<div id=\"emailBody\" style=\"min-width: 240px; max-width: 780px; display: block; margin: 0 auto; padding: 20px;\">\n<p style=\"text-align: left;\">\nDear Sir or Madam,\n<br /><br />\nWe are conducting research on your usage of our products and services.  This is your chance to make a difference in the way we do business.  Please take a moment to fill out this short survey.   Your answers will only be used in aggregate, and no personal information will be shared independent of the aggregated results.  Please be honest, as we take your answers and suggestions to heart.\n<br /><br />\nClick below to get started:\n</p>\n<p style=\"text-align: center;\">\n<a href=\"[surveyLink]\">Take our survey</a><br/>\n</p>\n<p style=\"text-align: center;\">\nResearch By Example | 1234 N Main St. | Anytown, CA 22313\n</p>\n<p style=\"text-align: center;\">\n<span style=\"font-size: 11px;\">\nIf you no longer wish to receive these emails, you may unsubscribe by clicking <a\nhref=\"[optOutLink]\">here</a>.\n</span>\n</p>\n</div>\n</div>\n&nbsp; <br/>",
  "reminder": "<div style=\"margin:0 auto;\">\n<div id=\"emailBody\" style=\"min-width: 240px; max-width: 780px; display: block; margin: 0 auto; padding: 20px;\">\n<p style=\"text-align: left;\">\nDear Sir or Madam,\n<br /><br />\nWe are conducting research on your usage of our products and services.  This is your chance to make a difference in the way we do business.  Please take a moment to fill out this short survey.   Your answers will only be used in aggregate, and no personal information will be shared independent of the aggregated results.  Please be honest, as we take your answers and suggestions to heart.\n<br /><br />\nClick below to get started:\n</p>\n<p style=\"text-align: center;\">\n<a href=\"[surveyLink]\">Take our survey</a><br/>\n</p>\n<p style=\"text-align: center;\">\nResearch By Example | 1234 N Main St. | Anytown, CA 22313\n</p>\n<p style=\"text-align: center;\">\n<span style=\"font-size: 11px;\">\nIf you no longer wish to receive these emails, you may unsubscribe by clicking <a\nhref=\"[optOutLink]\">here</a>.\n</span>\n</p>\n</div>\n</div>\n&nbsp; <br/>",
  "subject": "Share your feedback",
  "reminder_subject": "Reminder -- Share your feedback",
  "fromName": "FocusVision",
  "reminder_fromName": "FocusVision",
  "fromAddress": "invite@decipherinc.com",
  "reminder_fromAddress": "invite@decipherinc.com",
  "replyTo": "invite@decipherinc.com",
  "reminder_replyTo": "invite@decipherinc.com"
}

Shared lists

Create Shared List
POST/api/v1/surveys/{survey}/campaigns/shared

Upload a recipient list which will be available for campaigns in this survey. The recipient list is created, encrypted and immediately marked as “shared”. Using Campaign Manager the recipient list can be assigned to a campaign that doesn’t already have a recipient list.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/campaigns/shared
URI Parameters
HideShow
survey
string (required) 

path to survey. Requires Campaign Manager: Build permission.

data
an object list (required) 

either an array of JSON objects, a tab-delimited string with the data (UTF-8) or a base-64 encoded Excel 97 or 2007 file with data in the first sheet only

name
string (optional) 

Shared recipient list description which will be visible in Campaign Manager

Request
HideShow
Headers
Content-Type: with Excel file
Body
{
  "data": "UEsDBBQACAgIALyLdUsAAAAAAAAAAAAAA...",
  "name": "UK customers"
}
Request
HideShow
Headers
Content-Type: with JSON object as data
Body
{
  "data": [
    {
      "email": "bob@bobson.com",
      "name": "Bob Bobson"
    },
    {
      "email": "joe@joe.com",
      "name": "Joe Joeyson"
    }
  ],
  "name": "my_new_list"
}

Campaign List

Get Lists
GET/api/v1/surveys/{survey}/campaigns/{campaign}/list

Retrieve a list or seed list for a specific campaign.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/list
URI Parameters
HideShow
survey
string (required) 

path to survey

campaign
int (required) 

numeric campaign ID. The ID can be seen when editing the campaign or retrieved using the GET method above.

seed
string (optional) 

if the file being replaced should replace the seed list.

Create/Replace List
PUT/api/v1/surveys/{survey}/campaigns/{campaign}/list

Create a recipient list or seed list for this campaign. If the campaign has an existing list, the list will be replaced.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/list
URI Parameters
HideShow
survey
string (required) 

path to survey

campaign
int (required) 

numeric campaign ID. The ID can be seen when editing the campaign or retrieved using the GET method above.

seed
string (optional) 

if the file being created or replaced should be a seed list.

data
an object list (required) 

either an array of JSON objects, a tab-delimited string with the data (UTF-8) or a base-64 encoded Excel 97 or 2007 file with data in the first sheet only

Campaign Sends

Get Sends
GET/api/v1/surveys/{survey}/campaigns/{campaign}/sends

Retrieve a list of sends for a specific campaign.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/sends
URI Parameters
HideShow
survey
string (required) 

path to survey

campaign
int (required) 

numeric campaign ID. The ID can be seen when editing the campaign or retrieved using the GET method above.

Create a Send
POST/api/v1/surveys/{survey}/campaigns/{campaign}/sends

Start a send for a specific campaign.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/sends
URI Parameters
HideShow
survey
string (required) 

path to survey

campaign
int (required) 

numeric campaign ID. The ID can be seen when editing the campaign or retrieved using the GET method above.

type
string (required) 

send type (seed, soft, rest).

count
int (optional) 

number for participants to send (defaults to soft send maximum if not specified).

when
datetime (optional) 

scheduled time in epoch format (default delay will be used if not specified).

reminder
boolean (optional) 

indicate reminder sends. must be used with reminderFor (not required for reminder seed sends)

reminderFor
array (optional) 

list of valid send_id(s) of reminders to be sent

filters
array (optional) 

filter sends by variables in survey or campaign email list

suppressionListId
string (optional) 

add suppression email list to the send

fullThrottle
boolean (optional) 

setting true turns off email throttling entirely

Request
HideShow
Body
{
  "type": "reminder",
  "count": 2000,
  "when": "2020-05-16T22:30:00-07:00",
  "reminderFor": [
    23,
    11,
    54
  ],
  "filters": [
    {
      "list": "1",
      "locale": "en_US"
    },
    {
      "list": "2",
      "locale": "en_UK"
    }
  ],
  "suppressionListId": "7ZO4Xg"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "send_type": "soft",
  "when": "2020-04-24T23:15:57Z",
  "count": 2000,
  "send_id": 420,
  "campaign_id": 58,
  "survey": "selfserve/abc/abc12345,
  "send_status: "preparing",
  "reminder": false
}

Individual Send

Get a Send
GET/api/v1/surveys/{survey}/campaigns/{campaign}/sends/{send}

Retrieve a send for a specific campaign.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/sends/send
URI Parameters
HideShow
survey
string (required) 

path to survey

campaign
int (required) 

numeric campaign ID. The ID can be seen when editing the campaign or retrieved using the GET method above.

send
int (required) 

numeric send ID. The ID can be seen when editing the send, or retrieved using the GET method above.

Individual Send Cancel

Cancel a Send
POST/api/v1/surveys/{survey}/campaigns/{campaign}/sends/{send}/cancel

Cancel a send for a specific campaign.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/sends/send/cancel
URI Parameters
HideShow
survey
string (required) 

path to survey

campaign
int (required) 

numeric campaign ID. The ID can be seen when editing the campaign or retrieved using the GET method above.

send
int (required) 

numeric send ID. The ID can be seen when editing the send, or retrieved using the GET method above.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}

Status List

Get Email Status List
GET/api/v1/surveys/{survey}/campaigns/{campaign}/list/{send}

Retrieve the status of the emails sent out on a specific send.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/list/send
URI Parameters
HideShow
survey
string (required) 

path to survey

campaign
int (required) 

numeric campaign ID.

send
int (required) 

numeric send ID.

Suppression Lists

Get Suppression Lists
GET/api/v1/surveys/{survey}/campaigns/suppressions

Returns a list of available suppression lists for the specific project.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/suppressions
URI Parameters
HideShow
survey
string (required) 

path to survey

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "date": "2020-05-01T18:03:50Z",
    "suppression_id": "7ZO4Xg",
    "count": 3
  },
  {
    "date": "2020-05-05T18:04:38Z",
    "suppression_id": "wmAevJ",
    "count": 10
  }
]

Create Suppression List
PUT/api/v1/surveys/{survey}/campaigns/suppressions

Creates a list of emails to be suppressed when scheduling an email send.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/campaigns/suppressions
URI Parameters
HideShow
survey
string (required) 

path to survey

emails
array (required) 

array of emails to be suppressed

Request
HideShow
Body
{
  "emails": [
    "larry@example.com",
    "curly@example.com",
    "moe@example.com",
    "john@smith@example.com"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "valid_count": 3,
  "total": 4,
  "invalid_count": 1,
  "invalid": [
    "john@smith@example.com"
  ],
  "suppression_id": "7ZO4Xg"
}

Individual Suppression List

Get Suppression List
GET/api/v1/surveys/{survey}/campaigns/suppressions/{suppression}

Returns the emails of a suppression list.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/suppressions/suppression
URI Parameters
HideShow
survey
string (required) 

path to survey

suppression
string (required) 

suppression id

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  "larry@example.com",
  "curly@example.com",
  "moe@example.com"
]

Question Library

Survey Element Store

Save and reuse survey elements using the question library. Survey authors can add new elements to the library using this API or through the survey editor interface. Elements may be saved individually or grouped together to create a “set” or “template” of elements.

Element properties:

  • name (string): a description of the element

  • eid (string): the element’s ID (unique per server)

  • xml (string): the element’s survey XML representation

  • type (string): the type or class of element e.g. radio, html, set, subset (for answers)

  • tags (list): the element’s tags (e.g. short phrases to improve search)

  • private (boolean): true when the element is only accessible to the original author

  • locked (boolean): true when an element has reached a final state in development and should no longer change

  • shared (boolean): true when an element is global and available to all authors on the server

  • user_id (int): the original author’s user ID

  • user_ids (list): the list of author user IDs the element is shared with

  • group_ids (list): the list of group IDs the element is shared with

  • id (int): the system ID of the element

  • bid (string): the survey editor ID of the element

  • children (list): a list of child system IDs this element references

Get element
GET/api/v1/libraries/{company}/elements/{eid}

Retrieves a list containing a single library element.

Example URI

GET release.decipherinc.com/api/v1/libraries/company/elements/eid
URI Parameters
HideShow
company
string (required) 

company ID or name

eid
string (required) 

the unique element ID of the element to download

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
 {
  "name": "Intro Text",
  "xml": "<html label='q1'>Welcome to the survey!</html>",
  "type": "html",
  "eid": "8ca637a8",
  "tags": [],
  "private": true,
  "shared": false,
  "locked": false,
  "user_id": 492,
  "group_ids": [],
  "user_ids": [],
  "id": 24248,
  "uuid": 24248,
  "element_uuids": [],
 },
 ...
]

Add element
POST/api/v1/libraries/{company}/elements/{eid}

Add a new element to the library.

Example URI

POST release.decipherinc.com/api/v1/libraries/company/elements/eid
URI Parameters
HideShow
company
string (required) 

company ID or name

eid
string (required) 

the unique element ID of the element to upload (required, use _ to generate one randomly)

name
string (required) 

the name/description of the element

xml
string (optional) 

the survey XML representation of the element

xml_from_label
string (optional) 

the label of the question in the survey to use as the xml instead of specifying xml

tags
list (optional) 

a list of phrases to improve search/organization of the element

private
boolean (optional) 

use 1 to indicate the element should be private and visible to the original author only

locked
boolean (optional) 

use 1 to indicate this is a permanent element

shared
boolean (optional) 

use 1 to indicate this element should be available to all authors on a server (staff)

Request  /api/v1/libraries/self/elements/_ name="My New Element" xml="<html label=\"q1\">Hello</html>"
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "added": {
    "xml": "<html label=\"q1\">Hello</html>",
    "locked": false,
    "uuid": 24260,
    "bid": null,
    "imgs": {},
    "type": "html",
    "eid": "13765aca",
    "children": []
  }
}

Update element
PUT/api/v1/libraries/{company}/elements/{eid}

Update an element in the library.

Example URI

PUT release.decipherinc.com/api/v1/libraries/company/elements/eid
URI Parameters
HideShow
company
string (required) 

company ID or name

eid
string (required) 

the unique element ID of the element to edit

name
string (optional) 

the name/description of the element

tags
list (optional) 

a list of phrases to improve search/organization of the element

private
boolean (optional) 

use 1 to indicate the element should be private and visible to the original author only

locked
boolean (optional) 

use 1 to indicate this is a permanent element

shared
boolean (optional) 

use 1 to indicate this element should be available to all authors on a server (staff)

Request  /api/v1/libraries/self/elements/61af8cc2 name="My Updated Element"
Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Delete element
DELETE/api/v1/libraries/{company}/elements/{eid}

Remove an element from the library.

Example URI

DELETE release.decipherinc.com/api/v1/libraries/company/elements/eid
URI Parameters
HideShow
company
string (required) 

company ID or name

eid
string (required) 

the unique element ID of the element to remove

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Survey Elements Store

Get elements
GET/api/v1/libraries/{company}/elements/

Retrieves a list of all available survey elements.

Example URI

GET release.decipherinc.com/api/v1/libraries/company/elements/
URI Parameters
HideShow
company
string (required) 

company ID or name

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
 {
  "name": "Intro Text",
  "xml": "<html label='q1'>Welcome to the survey!</html>",
  "type": "html",
  "eid": "8ca637a8",
  "tags": [],
  "private": true,
  "shared": false,
  "locked": false,
  "user_id": 492,
  "group_ids": [],
  "user_ids": [],
  "id": 24248,
  "uuid": 24248,
  "element_uuids": [],
 },
 ...
]

Add elements
POST/api/v1/libraries/{company}/elements/

Add new elements to the library.

Example URI

POST release.decipherinc.com/api/v1/libraries/company/elements/
URI Parameters
HideShow
company
string (required) 

company ID or name

elements
list (required) 

list of element objects to upload

Request
HideShow
Body
[
  {
    "name": "New Element",
    "xml": "<html label=\"q1\">Hello</html>",
    "eid": "_"
  }
]
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "added": 1
}

Survey Elements

Get survey elements
GET/api/v1/libraries/{company}/surveys/{survey}/elements

Retrieve the survey elements from a specified survey.

Example URI

GET release.decipherinc.com/api/v1/libraries/company/surveys/selfserve/123/140001/elements
URI Parameters
HideShow
company
string (required) 

company ID or name

survey
string (required) Example: selfserve/123/140001

survey to retrieve the links for.

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "xml": "<block label=\"b1\">\n    <html id=\"ObIIe\" label=\"q1\">Hello</html>\n    <suspend id=\"Z396J\"/>\n  </block>\n",
    "type": "block",
    "children": [
      {
        "xml": "<html label=\"q1\">Hello</html>\n    ",
        "type": "html"
      },
      {
        "xml": "<suspend />\n  ",
        "type": "suspend"
      }
    ]
  }
]

Save Library Report Settings

Save library report settings for a library element
POST/api/v1/libraries/{company}/surveys/{survey}/report/{eid}

Save library report settings based on the company, project and library element id.

Example URI

POST release.decipherinc.com/api/v1/libraries/company/surveys/selfsrve/123/140001/report/eid
URI Parameters
HideShow
company
string (required) 

company ID or name

survey
string (required) Example: selfsrve/123/140001
eid
string (required) 

element id

questionLabel
string (required) Example: q1
Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Language Manager

Language Manager Application Data

You must have survey edit permissions to access this endpoint.

Get Language Manager Application Data
GET/api/v1/surveys/{survey}/mls/application/data

Returns data for the Language Manager application

  • Dupes (int): Number of translations with duplicates

  • Unique Dupes (int): Number of unique duplicates

  • Summary (object): Summary of each language present in survey

  • Survey Language List (array): Languages present in survey

  • Sys Languages (object): System languages available for use

  • Primary Language (string): Current primary language of survey

  • Resources (object): Information about each resource’s current status

    • identical (bool): Is this translation the same as the original
    • missing (bool): Is this translation missing
    • outdated (bool): Has this resource changed, therefore making this translation outdated

  • Unused Language List (array): Languages marked as unused in this survey

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/mls/application/data
URI Parameters
HideShow
survey
string (required) 

Path to your survey

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "DUPES": 2,
  "UNIQUE_DUPES": 1,
  "SUMMARY": {
    "english_ca": {
      "ok": 11,
      "name": "english_ca",
      "missing": 0,
      "primary": true,
      "nameFormatted": "English (Canada)",
      "version": 0,
      "identical": 0,
      "qualifieds": 0,
      "total": 11,
      "outdated": 0
    },
    "english": {
      "ok": 0,
      "name": "english",
      "missing": 11,
      "primary": false,
      "nameFormatted": "English",
      "version": 0,
      "identical": 0,
      "qualifieds": 0,
      "total": 11,
      "outdated": 0
    }
  },
  "SURVEY_LANGUAGE_LIST": [
    "english_ca",
    "english"
  ],
  "SYS_LANGUAGES": {
    "chinese": "Chinese",
    "german": "German",
    "german_austria": "German (Austria)",
    "macedonian": "Macedonian",
    "polish": "Polish",
    "spanish_latin": "Spanish (Latin America)",
    "swahili": "Swahili",
    "icelandic": "Icelandic",
    "turkish": "Turkish",
    "romanian": "Romanian",
    "aus": "English (Australia)",
    "spanish_argentina": "Spanish (Argentina)",
    "spanish_mexico": "Spanish (Mexico)",
    "arabic_uae": "Arabic (UAE)",
    "khmer": "Khmer",
    "english_ireland": "English (Ireland)",
    "hungarian": "Hungarian",
    "arabic_saudiarabia": "Arabic (Saudi Arabia)",
    "finnish": "Finnish",
    "arabic_lebanon": "Arabic (Lebanon)",
    "english_za": "English (South Africa)",
    "english_my": "English (Malaysia)",
    "serbian": "Serbian",
    "croatian": "Croatian",
    "portuguese": "Portuguese",
    "czech": "Czech",
    "french_lu": "French (Luxemborg)",
    "japanese": "Japanese",
    "persian": "Persian",
    "simplifiedchinese": "Chinese Simplified",
    "english_china": "English (China)",
    "english_g4": "English (Generic 4)",
    "english_g1": "English (Generic 1)",
    "english_g2": "English (Generic 2)",
    "english_g3": "English (Generic 3)",
    "spanish_chile": "Spanish (Chile)",
    "dutch": "Dutch",
    "traditionalchinese_tw": "Traditional Chinese (Taiwan)",
    "uk": "English (UK)",
    "spanish_brazil": "Spanish (Brazil)",
    "french": "French",
    "afrikaans": "Afrikaans",
    "traditionalchinese": "Chinese Traditional",
    "canadian": "French (Canada)",
    "albanian": "Albanian",
    "vietnamese": "Vietnamese",
    "spanish_peru": "Spanish (Peru)",
    "english_tw": "English (Taiwan)",
    "italian": "Italian",
    "slovak": "Slovak",
    "spanish": "Spanish",
    "tongan": "Tongan",
    "english_hk": "English (Hong Kong)",
    "arabic_egypt": "Arabic (Egypt)",
    "hindi": "Hindi",
    "danish": "Danish",
    "bulgarian": "Bulgarian",
    "spanish_eu": "Spanish (EU)",
    "simplifiedchinese_my": "Simplified Chinese (Malaysia)",
    "malay": "Malay",
    "russian": "Russian",
    "thai": "Thai",
    "kannada": "Kannada",
    "tamil": "Tamil",
    "dutch_belgium": "Dutch (Belgium)",
    "english_id": "English (Indonesia)",
    "german_lu": "German (Luxemborg)",
    "spanish_venezuela": "Spanish (Venezuela)",
    "tagalog": "Tagalog",
    "portuguese_br": "Portuguese (Brazil)",
    "indonesian": "Indonesian",
    "spanish_ecuador": "Spanish (Ecuador)",
    "mongolian": "Mongolian",
    "hebrew": "Hebrew",
    "arabic": "Arabic",
    "malay_sg": "Malay (Singapore)",
    "swedish": "Swedish",
    "english_india": "English (India)",
    "arabic_qatar": "Arabic (Qatar)",
    "samoan": "Samoan",
    "slovenian": "Slovenian",
    "english_sg": "English (Singapore)",
    "korean": "Korean",
    "french_belgium": "French (Belgium)",
    "english_ca": "English (Canada)",
    "english_nigeria": "English (Nigeria)",
    "latvian": "Latvian",
    "ukrainian": "Ukrainian",
    "lithuanian": "Lithunian",
    "simplifiedchinese_sg": "Simplified Chinese (Singapore)",
    "spanish_colombia": "Spanish (Colombia)",
    "norwegian": "Norwegian",
    "spanish_south": "Spanish (South America)",
    "estonian": "Estonian",
    "arabic_morocco": "Arabic (Morocco)",
    "slovene": "Slovene",
    "telugu": "Telugu",
    "punjabi": "Punjabi",
    "greek": "Greek",
    "burmese": "Burmese (Myanmar)",
    "english": "English"
  },
  "PRIMARY_LANGUAGE": "english_ca",
  "RESOURCES": [
    {
      "dupeCount": null,
      "resourceName": "general,name",
      "resource": "general,name",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "Survey",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": null,
      "resourceName": "samplesources,0,invalid",
      "resource": "samplesources,0,invalid",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "You are missing information in the URL. Please verify the URL with the original invite.",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": null,
      "resourceName": "samplesources,0,completed",
      "resource": "samplesources,0,completed",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "It seems you have already entered this survey.",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": null,
      "resourceName": "samplesources,0,inuse",
      "resource": "samplesources,0,inuse",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "Our records show that you are already taking this survey. If that's not correct, please wait 15 minutes and refresh this page. Thank you.",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": 2,
      "resourceName": "samplesources,0,exit:terminated,cdata",
      "resource": "samplesources,0,exit:terminated,cdata",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "Thank you for taking our survey.",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": null,
      "resourceName": "samplesources,0,exit:qualified,cdata",
      "resource": "samplesources,0,exit:qualified,cdata",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "Thank you for taking our survey. Your efforts are greatly appreciated!",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": 2,
      "resourceName": "samplesources,0,exit:overquota,cdata",
      "resource": "samplesources,0,exit:overquota,cdata",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "Thank you for taking our survey.",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": null,
      "resourceName": "q1,title",
      "resource": "q1,title",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "New Single Select Question",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": null,
      "resourceName": "q1,comment",
      "resource": "q1,comment",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "Select one",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": null,
      "resourceName": "q1,r1,cdata",
      "resource": "q1,r1,cdata",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "Sample Row #1",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    },
    {
      "dupeCount": null,
      "resourceName": "q1,r2,cdata",
      "resource": "q1,r2,cdata",
      "status": [
        {
          "identical": false,
          "language": "english",
          "missing": true,
          "text": "",
          "isDisplayedInThisLanguage": true,
          "isPrimary": false,
          "outdated": false
        },
        {
          "identical": false,
          "language": "english_ca",
          "missing": false,
          "text": "Sample Row #2",
          "isDisplayedInThisLanguage": true,
          "isPrimary": true,
          "outdated": false
        }
      ]
    }
  ],
  "UNUSED_LANGUAGE_LIST": []
}

Application Translations

Update app translations
PUT/api/v1/surveys/{survey}/mls/application/translations

Updates translations for Language Manager application.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/mls/application/translations
URI Parameters
HideShow
survey
string (required) 

path to survey

resourceTranslations
object (required) 

translated survey resource

Resource Translation

Update translation
PUT/api/v1/surveys/{survey}/mls/translation/{resource}

Updates a single translation resource

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/mls/translation/resource
URI Parameters
HideShow
survey
string (required) 

path to survey

resource
string (required) 

resource to be translated

lang
string (required) 

target language for the translation

text
string (required) 

translated resource

Primary Language

Update primary language
PUT/api/v1/surveys/{survey}/mls/languages/primary/{lang}

Changes the surveys primary language.

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/mls/languages/primary/lang
URI Parameters
HideShow
survey
string (required) 

path to survey

lang
string (required) 

sets a language as the primary language of the project

Other Languages

Put
PUT/api/v1/surveys/{survey}/mls/languages/{lang}

Adds a language to the survey (otherLanguages)

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/mls/languages/lang
URI Parameters
HideShow
survey
string (required) 

path to survey

lang
string (required) 

sets a language as the primary language of the project

Delete
DELETE/api/v1/surveys/{survey}/mls/languages/{lang}

Removes a language from the survey (otherLanguages)

Example URI

DELETE release.decipherinc.com/api/v1/surveys/survey/mls/languages/lang
URI Parameters
HideShow
survey
string (required) 

path to survey

lang
string (required) 

sets a language as the primary language of the project

Unused Languages

Put
PUT/api/v1/surveys/{survey}/mls/languages/unused/{lang}

Marks a language as unused (unusedLanguages)

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/mls/languages/unused/lang
URI Parameters
HideShow
survey
string (required) 

path to survey

lang
string (required) 

sets a language as the primary language of the project

Delete
DELETE/api/v1/surveys/{survey}/mls/languages/unused/{lang}

Restores a language previously marked as ‘unused’ (unusedLanguages)

Example URI

DELETE release.decipherinc.com/api/v1/surveys/survey/mls/languages/unused/lang
URI Parameters
HideShow
survey
string (required) 

path to survey

lang
string (required) 

sets a language as the primary language of the project

GET and POST translations

Get translations
GET/api/v1/translation

Translations are returned for the first survey found or the one specified by start. A lastRetrievedId argument is returned with the result that can be specified as the start to get translations for the next survey.

Example URI

GET release.decipherinc.com/api/v1/translation
URI Parameters
HideShow
start
string (optional) 

If specified, translations for the survey provided will be returned otherwise it will be the first survey found

paths
array (optional) 

An array of paths to include. If not provided all surveys with tapiDue set are considered

aggregateDupes
boolean (required) 

Defaults to true. Set to false if duplicate translations should appear separately.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "postbackJobId": "",
  "targetLanguages": [],
  "expectedDueDate": 1355270400,
  "sourceLanguage": "en-US",
  "projectId": "",
  "schemaId": "v1",
  "lastRetrievedId": "selfserve/53a/171202",
  "requests": [
    {
      "icuFormat": false,
      "elements": [
        {
          "targetString": "The URL above does not include the proper information to be included in this survey. Please review your invite email for the proper URL, and contact the individual specified if problems persist.",
          "sourceString": "The URL above does not include the proper information to be included in this survey. Please review your invite email for the proper URL, and contact the individual specified if problems persist.",
          "elementId": "samplesources,1,invalid"
        },
        {
          "targetString": "Thank you for your interest but it seems you have already finished this survey.",
          "sourceString": "Thank you for your interest but it seems you have already finished this survey.",
          "elementId": "samplesources,1,completed"
        },
        {
          "targetString": "Our records show that you are already taking this survey. If that's not correct, please wait 15 minutes and refresh this page. Thank you.",
          "sourceString": "Our records show that you are already taking this survey. If that's not correct, please wait 15 minutes and refresh this page. Thank you.",
          "elementId": "samplesources,1,inuse"
        }
      ],
      "documentId": "selfserve/53a/171201"
    }
  ]
}

Post translations
POST/api/v1/translation

Add in translations for a specified survey and language. When translations are added any reservation for that survey and language combination are removed. NOTE: if sourceString no longer matches the text in XML, the translation will be accepted but the ID will appear in the “oudated” output array.

Example URI

POST release.decipherinc.com/api/v1/translation
URI Parameters
HideShow
targetLanguages
array (required) 

An array containing a string of the language to be translated

requests
array (required) 

A list of objects containing a document id and a list of elements.

  • documentId (string)… Path to the survey

  • elements (array)… List of objects containing the elementId, sourceString and targetString

aggregateDupes
boolean (required) 

Defaults to true. Set to false if dupes were not aggregated when pulling translations.

postbackJobId
str (required) 

The jobid for the reservation that was created for this document.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "identical": 0,
  "changed": 10,
  "outdated": [],
  "invalid_label": []
}

Translation Delta

Get Translation Delta
GET/api/v1/translation/delta

Return any untranslated (or outdated) unreserved resources translations for a survey

Example URI

GET release.decipherinc.com/api/v1/translation/delta
URI Parameters
HideShow
start
string (optional) 

If specified, translations for the survey provided will be returned otherwise it will be the first survey found

paths
array (optional) 

An array of paths to include. If not provided all surveys with tapiDue set are considered

aggregateDupes
boolean (required) 

Defaults to true. Set to false if duplicate translations should appear separately.

Translation API Reservations

The translation reservation system is used to mark translations which have already been pulled for translating and to prevent translation deltas from being pulled multiple times.

Get translation reservations
GET/api/v1/translation/delta/reservation

Returns active reservations

Example URI

GET release.decipherinc.com/api/v1/translation/delta/reservation
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "ackDatas": [
  {
   "requests": [
    {
     "documentId": "selfserve/53a/171200"
    },
    {
     "documentId": "selfserve/53a/171201"
    }
   ],
   "targetLanguages": [
    "es",
    "ja"
   ],
   "jobId": "01e80a5cb03e4aa19521513c57e91f08"
  },
  {
   "requests": [
    {
     "documentId": "selfserve/53a/171202"
    }
   ],
   "targetLanguages": [
    "ar-LB"
   ],
   "jobId": "1195619ab8854e3ca81b593183edd398"
  }
}

Add translation reservation
POST/api/v1/translation/delta/reservation

Add a new reservation

Example URI

POST release.decipherinc.com/api/v1/translation/delta/reservation
URI Parameters
HideShow
ackDatas
array (required) 

An array of objects containing information about the reservation

  • targetLanguages (array)… An array of languages to be reserved

  • requests (array)… An array of objects containing documentId which should be the path to the survey

  • jobId (str)… A unique jobId to identify the reservation

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "requests": [
      {
        "documentId": "selfserve/53a/170201"
      }
    ],
    "targetLanguages": [
      "es"
    ],
    "jobId": "e724ce5c5b8b4eb08e50dda26ee89aac"
  }
]

Delete translation reservations

Delete
POST/api/v1/translation/delta/reservation/delete

Delete reservations by their jobIds

Example URI

POST release.decipherinc.com/api/v1/translation/delta/reservation/delete
URI Parameters
HideShow
reason
string (required) 

A reason for the reservation cancellation

cancelledBy
string (required) 

Who is canceling this reservation

jobIds
array (required) 

An array of jobIds to cancel

Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Project Parameters

Project parameters

Get Project Parameters
GET/api/v1/parameters/list/{survey}

Returns an object of available project parameters. Requires survey edit or data edit permission for the project.

Example URI

GET release.decipherinc.com/api/v1/parameters/list/survey
URI Parameters
HideShow
survey
string (required) 

survey path

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "includeInRespondentData": true,
 "parameters": [
  {
   "title": "Question title",
   "type": "select",
   "options": [
    {
     "label": "option_1",
     "value": "option 1 value",
     "title": "Option 1"
    },
    {
     "label": "option_2",
     "value": "option 2 value",
     "title": "Option 2"
    }
 ]
}

Update project parameters

Put Project Parameters
PUT/api/v1/parameters/update/{survey}

Sends an object of selected project parameters. Requires survey edit or data edit permission for the project.

Example URI

PUT release.decipherinc.com/api/v1/parameters/update/survey
URI Parameters
HideShow
survey
string (required) 

survey path

parameters
object (required) 

project parameters

Saved project parameters

Get Saved Project Parameters
GET/api/v1/parameters/{survey}

Returns an object of saved project parameters. Requires survey edit or data edit permission for the project.

Example URI

GET release.decipherinc.com/api/v1/parameters/survey
URI Parameters
HideShow
survey
string (required) 

survey path

Validate project parameters

Validate Project Parameters
GET/api/v1/parameters/validate/{survey}

Validates saved project parameters and returns an array of errors. Requires survey edit or data edit permission for the project.

Example URI

GET release.decipherinc.com/api/v1/parameters/validate/survey
URI Parameters
HideShow
survey
string (required) 

survey path

Set project parameters configuration

Set Project Parameters
POST/api/v1/parameters/config

Set project parameters configuration to a company/subdirectory folder. Requires supervisor access.

Example URI

POST release.decipherinc.com/api/v1/parameters/config
URI Parameters
HideShow
company
string (required) 

company name

subdirectory
string (optional) 

subdirectory name

parameters
object (required) 

project parameters configuration

Disable project parameters

Disable Project Parameters
PUT/api/v1/parameters/disable

Disable project parameters configuration. Requires supervisor access.

Example URI

PUT release.decipherinc.com/api/v1/parameters/disable
URI Parameters
HideShow
company
string (required) 

company name

subdirectory
string (optional) 

subdirectory name

disabled
boolean (required) 

disable project parameters

Video Management

Upload Video File

You must have survey edit permissions to access this endpoint.

Upload video file
POST/api/v1/surveys/{survey}/videos

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/videos
URI Parameters
HideShow
survey
string (required) 

Path to your survey

source
string (required) 

This is the URL (must include filename and extension) to upload.

description
string (optional) Default: filename 

The video description that will be displayed in file manager.

privacy
string (optional) Default: project 

Where the videos will be displayed in file manager.

  • project: shows only to the project it was uploaded to.

  • company: shows to all projects in the users company.

unique_watermarks
boolean (optional) Default: 0 

  • 0: the video is uploaded without burned-in watermarking.

  • 1: the video is processed with burned-in watermarking.

quantity
int (optional) 

If unique_watermarks is true, this sets the number of unique videos that will be created. Must be 1 - 10,000.

unique_watermark_options
dict (optional) 

Customizations to the watermark.

position
string (optional) Default: middle center 

Position of the watermark on the video. Options

  • top left

  • top center

  • top right

  • middle left

  • middle center

  • middle right

  • bottom right

  • bottom center

  • bottom left

color
string (optional) Default: rgba(255, 255, 255, 64) 

Color of the watermarked text Acceptable Formats:

  • HEX #FFFFFF

  • RGB/A rgb(0, 0, 0) rgba(255, 255, 255, 128)

  • HSL hsl(0, 100%, 50%)

  • Common HTML colors red, yellow, green, etc.

size
string (optional) Default: 70% 

Size of the watermark as a percentage of the video width in increments of 10.

Request
HideShow
Body
{
  "source": "https://www.mydomain.com/videos/video_file.mp4",
  "description": "My Domains Video File.",
  "privacy": "company",
  "unique_watermarks": 1,
  "quantity": 50,
  "unique_watermark_options": {
    "position": "bottom middle",
    "color": "#000000",
    "size": "60%"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "video_id": "93472979349"
}

Set Watermarked Video Total

You must have survey edit permissions to access this endpoint.

Increase Unique Videos
PUT/api/v1/surveys/{survey}/videos/{video_id}

Increases the number of unique videos

Example URI

PUT release.decipherinc.com/api/v1/surveys/survey/videos/video_id
URI Parameters
HideShow
survey
string (required) 

Path to your survey

video_id
string (required) 

The ID of the video to update.

quantity
int (required) 

The new total number of unique videos. Difference between old and new quantities cannot exceed 10,000 (i.e., only 10,000 more can be requested at a time.)

keep
boolean (optional) 

If True then the video will be flagged so as it is not deleted by the cleanup scripts.

Request
HideShow
Body
{
  "quantity": 500
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{}

Get Videos

You must have survey edit permissions to access this endpoint.

Get Videos
GET/api/v1/surveys/{survey}/videos

Get the list of all video files.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/videos
URI Parameters
HideShow
survey
string (required) 

Path to your survey

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "video_id": "93472979349",
    "privacy": "company",
    "description": "Video Description",
    "filename": "filename.mp4",
    "status": "processing",
    "watermarked": false,
    "watermarked_quantity": 0,
    "keep": true
  },
  {
    "video_id": "43597293",
    "privacy": "project",
    "description": "Video Description",
    "filename": "filename.mp4",
    "status": "processing",
    "watermarked": true,
    "watermarked_quantity": 50,
    "keep": false
  }
]

Get Video

You must have survey edit permissions to access this endpoint.

List Video
GET/api/v1/surveys/{survey}/videos/{video_id}

Get an individual video.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/videos/video_id
URI Parameters
HideShow
survey
string (required) 

Path to your survey

video_id
string (required) 

ID of the video to retrieve.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "video_id": "93472979349",
  "privacy": "company",
  "description": "Video Description",
  "filename": "filename.mp4",
  "status": "processing",
  "watermarked": true,
  "ready": 75,
  "quantity": 100,
  "keep": false
}

Get Watermark Videos

You must have survey edit permissions to access this endpoint.

List Watermark Videos
GET/api/v1/surveys/{survey}/videos/{video_id}/watermark_videos

Get the list of watermarks and video IDs.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/videos/video_id/watermark_videos
URI Parameters
HideShow
survey
string (required) 

Path to your survey

video_id
string (required) 

ID of the watermarked video to retrieve.

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "video_id": "93472979349",
    "watermark_id": "87fg8gd8"
  },
  {
    "video_id": "93472979349",
    "watermark_id": "87fg8gd8"
  }
]

Create Watermark DB File

You must have survey edit permissions to access this endpoint.

Create Watermark File
POST/api/v1/surveys/{survey}/videos/{video_id}/create_db_file

Create a file containing a single column of {video_id}.{watermark_id}, which the Video Player DQ uses to uniquely assign videos to participants.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/videos/video_id/create_db_file
URI Parameters
HideShow
survey
string (required) 

Path to your survey

video_id
string (required) 

ID of the watermarked video.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "database_file": "watermark_videos_12323543345.txt"
}

Miscellaneous

Status

Get Task
GET/api/v1/status

Retrieve the status of an async task started by another api call

Example URI

GET release.decipherinc.com/api/v1/status
URI Parameters
HideShow
id
string (required) 

id of the async task to get the status of

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "finished",
  "what": "Finished",
  "ident": "3jd7qyadpgjbxu6t",
  "timestamp": 1516830993,
  "extra": {
    "languages": null,
    "maxStoredSize": 0,
    "cpuTime": 0.022321394999999997,
    "markerCount": 1,
    "progressCount": 200,
    "dataCleared": false
  },
  "pid": 3957,
  "task": "Survey Stress Test",
  "survey": "selfserve/53a/180109",
  "result": "100/100 succeeded",
  "progress": 100,
  "percentage": 100,
  "total": 100,
  "type": "sst"
}

Scheduling

Get Logic Events
GET/api/v1/schedule

Decipher 29. Retrieve an array of events scheduled for any survey that you are able to access. Those events can only be created by logic nodes. Fields returned:

  • retries number of times execution of this event has been retried due to some API error

  • completed true if that item has been completed, false if it was scheduled

  • tstamp the timestamp of next attempted execution of the event

  • element_type the logic node type responsible

  • element the label of the element responsible

  • originally_scheduled the time the event was originally scheduled for. This remains fixed, while tstamp can update as the event is retried

  • scheduling English description of how this event is being scheduled

  • path path to the survey

  • id internal event ID

  • element_title English description of the action provided by the element

Example URI

GET release.decipherinc.com/api/v1/schedule
Response  200
HideShow
Body
[
  {
    "retries": 0,
    "completed": true,
    "tstamp": "2015-07-18T21:35:00Z",
    "element_type": "close",
    "originally_scheduled": "2015-07-18T21:35:00Z",
    "scheduling": "once",
    "path": "my/survey/path",
    "element": "close",
    "id": 2,
    "element_title": "Close a survey at a certain point"
  }
]

Debug logic

Debug Logic
GET/api/v1/surveys/{survey}/logic/{label}/debug

Retrieve a list of debug messages for a given logic node.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/logic/label/debug
URI Parameters
HideShow
survey
string (required) 

Path to your survey

label
string (required) 

Label of the logic node

Trigger logic

Trigger Logic
POST/api/v1/surveys/{survey}/logic/{label}/trigger

Run the code associated with this logic node. Decipher 29.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/logic/label/trigger
URI Parameters
HideShow
survey
string (required) 

survey to trigger in. You must be able to edit the survey to trigger the action

label
string (required) 

label of the logic to trigger

reschedule
bool (required) Default: false 

after triggering, reschedule a periodic logic to its next execution time. Internal use only.

Hello Service

Hello there!
GET/api/v1/hello

This test call echos its name argument.

Example URI

GET release.decipherinc.com/api/v1/hello
URI Parameters
HideShow
name
string (required) 

this object wil be echoed back

Request
HideShow
Body
{
  "name": "Roy Fielding"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "ok": "1",
  "hello": "Roy Fielding"
}

API metadata

Get API metadata
GET/api/v1/meta

Retrieve an array of all currently implemented API calls.

Following properties are available:

  • endpoint name of the API call, excluding version but including the placeholder for primary key of the source.

  • description description (using Markdown format). This information comes from this very document

  • title API title

  • url URL including current version prefix

  • args object containing arguments this API call will take, together with type names

  • method method to use. Note: multiple entries will exist with same endpoint but different methods

Example URI

GET release.decipherinc.com/api/v1/meta
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
 {
  "endpoint": "rh/apikeys/{apikey}",
  "description": "Deactivate an API key. Keys that were created and never used are deleted; others are mar
ked as inactive for audit\npurposes. The `deleted` value in the response will tell you whether the key was
 completely erased or just inactivated.",
  "title": "Retire",
  "url": "/api/v1/rh/apikeys/{apikey}",
  "args": {
   "apikey": "str"
  },
  "method": "DELETE"
 },
 {
  "endpoint": "meta",
  "description": "Retrieve an array of all currently implemented API calls.\n\nFollowing properties are available:\n\n* `endpoint` name of the API call, excluding version but including the placeholder for primary key of the source. \n\n* `description` description (using Markdown format). This information comes from this very document\n\n* `title` API title\n\n* `url` URL including current version prefix\n\n* `args` object containing arguments this API call will take, together with type names\n\n* `method` method to use. Note: multiple entries will exist with same endpoint but different methods\n\n**History**: Added in `Beacon 26`.",
  "title": "Get",
  "url": "/api/v1/meta",
  "args": {},
  "method": "GET"
 },
 ]

System Information

Get
GET/api/v1/sysinfo

Retrieve interesting data bout the current version of Beacon software as well as the hardware. Requires Staff.

  • changeset internal version control ID describing the exact software version

  • clientContact who at the client is responsible for the server

  • client Name of the client (i.e. company we run this Beacon instance for)

  • cloudfront URL of the Amazon Cloudfront host used if any

  • coordinates latitude and longitude for the server’s location

  • cpuCount number of virtual CPUs

  • cpu CPU used in the server

  • datacenter the codename for ISP’s datacenter

  • decipherContact who at Decipher is responsible for the server (typically account manager)

  • development boolean is this a development instance?

  • disk disk space available on disks used by Beacon.

  • evalErrors email address for delivering survey-level errors

  • geoip Does this server have a geoIP license?

  • hostname internal host name

  • instance typically always “v2”

  • isp Name of the ISP used to host the server (e.g. “Rackspace”)

  • MAX_COMPAT maximum compat level for surveys (always 100 + release)

  • memoryFree Free memory (unused memory plus buffers and cache)

  • memoryTotal Total amount of installed memory (in kiloBytes)

  • oauth2 Is Oauth2 authentication enabled?

  • protos is the PRO-T-S system enabled?

  • release release number (e.g. Beacon 25 is returned as 25)

  • saml Is SAML2 authentication enabled?

  • secure base secure URL (normally the https version of url)

  • systemErrors email address for delivering system-level errors

  • uglify post-process Javascript files using jsuglify to optimize them

  • url base URL prefixed to any pages such as /survey

Example URI

GET release.decipherinc.com/api/v1/sysinfo
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "changeset": "2714cfcbf399",
 "secure": 'https://selfserve.decipherinc.com',
 "decipherContact": "helpdesk@decipherinc.com",
 "MAX_COMPAT": 126,
 "protos": false,
 "disk": {
  "/home/hermes/v2": {
   "bytes": 492098977792,
   "freeInodes": 28757954,
   "freeBytes": 124230008832
  }
 },
 "cpu": "Intel(R) Core(TM) i7-2600K CPU @ 3.40GHz",
 "uglify": false,
 "saml": false,
 "hostname": "ares.decipherinc.com",
 "coordinates": [
  41.9932891,
  -87.9577367
 ],
 "instance": "v2",
 "cpuCount": 8,
 "systemErrors": "hermes-system-errors@decipherinc.com",
 "development": true,
 "cloudfront": null,
 "datacenter": "ORD",
 "oauth2": true,
 "evalErrors": "hermes-eval-errors@decipherinc.com",
 "url": "http://selfserve.decipherinc.com",
 "geoip": true,
 "memoryTotal": 16410800,
 "isp": "Rackspace",
 "client": "Decipher Inc.",
 "memoryFree": 4146556,
 "release": 26,
 "clientContact": "helpdesk@decipherinc.com"
}

Update
PUT/api/v1/sysinfo

This can be used to modify the configurable settings such as client name, client contact etc.

Example URI

PUT release.decipherinc.com/api/v1/sysinfo
URI Parameters
HideShow
values
object (required) 

object containing the new values. Values not referenced are left unchanged.

Error debugging

Find error
GET/api/v1/exceptions/search

Search for a logged error by lookup code. Returns the following properties:

  • timestamp – time that the error occurred

  • path – survey path (if applicable)

  • full_text – full error text and traceback (if applicable)

Example URI

GET release.decipherinc.com/api/v1/exceptions/search
URI Parameters
HideShow
lookup_code
str (required) 

lookup code

Internal API calls

These API calls are reserved for internal Decipher usage. Changes to them may happen at any time outside of the normal stable versioning process.

Settings

Get current value
GET/api/v1/settings/{scope}/{key}

Retrieve the current value of a setting explicitly put at this scope. I.e. if a setting has been configured global, you must call it with scope set to “global” to find it. See the “effective” API call below for finding the current effective value for a certain scope, taking into the cascading order of global -> company -> survey.

This endpoint is restricted to FV staff only.

Example URI

GET release.decipherinc.com/api/v1/settings/scope/key
URI Parameters
HideShow
scope
string (required) 

Either “global”, “company:company-name” or “survey:survey-path”. This determines at what level the setting applies. Settings are checked for Survey, Company, Global, stopping at the first match.

key
string (required) 

One of the possible setting keys. Please see the KB for a current list.

Response  200
HideShow
Body
{
  "scope": "company:1178",
  "updated_by": "eandreasen@focusvision.com",
  "key": "comprehend.limit",
  "value": 10000,
  "updated_on": "2020-08-24T19:53:15Z"
}

Update value
PUT/api/v1/settings/{scope}/{key}

Set or update the value of a setting for a given scope.

This endpoint is restricted to FV staff only.

Example URI

PUT release.decipherinc.com/api/v1/settings/scope/key
URI Parameters
HideShow
scope
string (required) 

Either “global”, “company:company-name” or “survey:survey-path”. This determines at what level the setting applies. Settings are checked for Survey, Company, Global, stopping at the first match.

key
string (required) 

One of the possible setting keys. Please see the KB for a current list.

value
object (required) 

The new value. The type of this value will vary depending on key, please see KB.

add
str (required) 

Feature flag that will be enabled for the given scope (key: flags).

Delete value
DELETE/api/v1/settings/{scope}/{key}

Removes a setting entirely. If the setting is configured at a wider scope, that scope’s value will now be used.

This endpoint is restricted to FV staff only.

Example URI

DELETE release.decipherinc.com/api/v1/settings/scope/key
URI Parameters
HideShow
scope
string (required) 

Either “global”, “company:company-name” or “survey:survey-path”. This determines at what level the setting applies. Settings are checked for Survey, Company, Global, stopping at the first match.

key
string (required) 

One of the possible setting keys. Please see the KB for a current list.

Effective Setting for a Survey

Get Effective Setting
GET/api/v1/settings/effective/survey/{survey}/{key}

Given this survey path, what is the effective setting for this key? Returns the scope it was found in as well as its value.

This endpoint is restricted to FV staff only.

Example URI

GET release.decipherinc.com/api/v1/settings/effective/survey/survey/key
URI Parameters
HideShow
survey
string (required) 

The survey path for which to get the given setting

key
string (required) 

The name of the setting to get

Response  200
HideShow
Body
{
  "scope": "company",
  "value": 500
}

Effective Public Settings for a Survey

Get Public Settings
GET/api/v1/settings/public/survey/{survey}

Returns effective settings values for the given survey for each publicly accessible setting.

Example URI

GET release.decipherinc.com/api/v1/settings/public/survey/survey
URI Parameters
HideShow
survey
string (required) 

The survey path for which to get the given setting

Response  200
HideShow
Body
{
  "odata.variables": 1000
}

Settings History

Get Settings History
GET/api/v1/settings/{scope}/{key}/history

Lists all previous values of a setting for the given scope, what their previous values were, and by whom they were changed.

This endpoint is restricted to FV staff only.

Example URI

GET release.decipherinc.com/api/v1/settings/scope/key/history
URI Parameters
HideShow
scope
string (required) 

Either “global”, “company:company-name”, or “survey:survey-path”.

key
string (required) 

One of the possible setting keys. Please see the KB for a current list.

Response  200
HideShow
Body
[
  {
    "updated_by": "developer@decipherinc.com",
    "prev_value": null,
    "key": "odata.variables",
    "new_value": "500",
    "updated_on": "2020-11-20T00:13:59Z",
    "scope": "company:1"
  },
  {
    "updated_by": "developer@decipherinc.com",
    "prev_value": "500",
    "key": "odata.variables",
    "new_value": "300",
    "updated_on": "2020-11-20T00:40:06Z",
    "scope": "company:1"
  }
]

Database backups

Get
GET/api/v1/surveys/{survey}/delphi/backups

Return an array of backups for that survey. Backups are done if you clear ALL data, for example by running SST. Each backup item is an object containing name (the backup’s unique name), path (the surey path), bytes (size of the backup in the database system) records (number of respondents) and created_on (time of creation). Earliest backups come first.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/delphi/backups
URI Parameters
HideShow
survey
string (required) 

The Delphi survey whose backups you want to examine

Response  200
HideShow
Body
[
  {
    "path": "demo/2474/data.clear",
    "created_on": "2020-06-26T21:04:54Z",
    "bytes": 40960,
    "name": "demo_a7rinxvnk8mkqk2y$qhxsw",
    "records": 0
  },
  {
    "path": "demo/2474/data.clear.1593121619",
    "created_on": "2020-06-26T21:04:54Z",
    "bytes": 147456,
    "name": "demo__8vftmpgexocrsqxklbtog",
    "records": 50
  },
  {
    "path": "demo/2474/data.clear.1593205588",
    "created_on": "2020-06-26T21:06:28Z",
    "bytes": 114688,
    "name": "demo_gi9dks8mlk0cuoxo14ttqa",
    "records": 50
  }
]

Specific database backup

Peek
GET/api/v1/surveys/{survey}/delphi/backups/{backup}

Peek at the content of a backup. Use the name property from the backup list as parameter here. It’s recommended to pass in top=10 to extract only the first 10 items. Status, UUID and extra-variables but not actual data is returned here.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/delphi/backups/backup
URI Parameters
HideShow
survey
string (required) 

The Delphi survey whose backups you want to examine

backup
string (required) 

The backup (identified by name from the backup list

Response  200
HideShow
Body
[
  {
    "status": "q",
    "created_on": "2020-06-25T22:42:53Z",
    "uuid": "zvk3nfeexafyq1ch",
    "evars": {
      "record": "1",
      "url": "http://localhost:5000/survey/demo/2474",
      "list": "1",
      "dcua": "si",
      "source": "",
      "session": "07mv2su11skcb90j",
      "userAgent": "Mozilla/5.0 (iPhone; U; CPU OS 4_2_1 like Mac OS X) AppleWebKit/532.9 (KHTML, like Gecko) Version/5.0.3 Mobile/8B5097d Safari/6531.22.7"
    }
  },
  {
    "status": "q",
    "created_on": "2020-06-25T22:42:53Z",
    "uuid": "4t84apgjhxkr3yb2",
    "evars": {
      "record": "5",
      "url": "http://localhost:5000/survey/demo/2474",
      "list": "1",
      "dcua": "..",
      "source": "",
      "session": "awd8bnhxhydb8mag",
      "userAgent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.0; Trident/5.0; BOIE9;ENGB)"
    }
  }
]

Restore

Restore
POST/api/v1/surveys/{survey}/delphi/backups/{backup}/restore

Restore a backup. This copies all the data in the backup into the main survey. An error occurs if the backup was already restored in the past.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/delphi/backups/backup/restore
URI Parameters
HideShow
survey
string (required) 

The Delphi survey whose backups you want to examine

backup
string (required) 

The backup (identified by name) from the backup list

Legacy data

Get
GET/api/v1/tasks/delphi-legacy

Enumerate legacy data for surveys under a given path. Legacy data files are files for surveys that have been converted to Delphi. Those are not automatically removed normally. These are files like results.bin, variables.dat. etc residing in the data/ directory.

The return value is an array of the surveys with removable files, each survey being identified under the path key. The total amount of bytes per directory is included under the removable key. If the legacy data file contains an UUID that does not exist in the Delphi database, a non-zero value will be under the missing key.

You need survey.edit access to view or delete legacy files.

Example URI

GET release.decipherinc.com/api/v1/tasks/delphi-legacy
URI Parameters
HideShow
base
string (required) 

The base path to start the search at, e.g. selfserve/1234 for an entire client directory

Response  200
HideShow
Body
[
  {
    "path": "demo/quote",
    "removable": 2612,
    "missing": 0
  },
  {
    "path": "demo/valid",
    "removable": 113035,
    "missing": 1
  }
]

Delete
DELETE/api/v1/tasks/delphi-legacy

Delete the legacy files. For each path with successfully deleted files, an object is returned with removed containing the list of removed files, and failed list of any files that could not be removed due to permission issues.

Example URI

DELETE release.decipherinc.com/api/v1/tasks/delphi-legacy
URI Parameters
HideShow
base
string (required) 

The base path to start the search at, e.g. selfserve/1234 for an entire client directory

Response  200
HideShow
Body
[
  {
    "path": "demo/d5",
    "removed": [
      "virtual.fingerprint",
      "results.strings",
      "data.db",
      "variables.dat",
      "virtual.bin",
      "virtual.strings",
      "last-record",
      "results.bin",
      ".cache.times"
    ],
    "failed": []
  }
]

Data storage

Decipher 28 Allows storage of a JSON object. The objects stored are currently private to each user storing them and cannot currently be read or written by anyone else.

Get
GET/api/v1/storage/{app_id}/{bucket}/{id}

Retrieves an object. Returns 404 if not found. Field in the response:

  • accessed_on (date) last access time
  • updated_by ID of the user who last modified this file
  • created_by ID of the creator
  • created_on date of creation
  • updated_on time of update
  • id, app_id, bucket – these identify the item
  • data the data object

Example URI

GET release.decipherinc.com/api/v1/storage/app_id/bucket/id
URI Parameters
HideShow
default
object (required) 

If specified and the key does not already exist it’s created with this value and returned

id
string (required) 
app_id
string (required) 
bucket
string (required) 

Delete
DELETE/api/v1/storage/{app_id}/{bucket}/{id}

Removes an object. Deleted objects can be restored, but there is no currently no API to do so.

Example URI

DELETE release.decipherinc.com/api/v1/storage/app_id/bucket/id
URI Parameters
HideShow
id
string (required) 
app_id
string (required) 
bucket
string (required) 

Update
PUT/api/v1/storage/{app_id}/{bucket}/{id}

Updates an object with new data.

Example URI

PUT release.decipherinc.com/api/v1/storage/app_id/bucket/id
URI Parameters
HideShow
id
string (required) 
app_id
string (required) 
bucket
string (required) 
data
object (required) 

Logic node library

Get list of nodes
GET/api/v1/logiclib

Retrieves the list of logic nodes for the entire server or also available to specific survey. Specifying a survey will include client or survey specific nodes. The return value is an array of objects, one for each logic node containing:

  • kb – ID of the knowledge base page containing the documentation

  • releaseDate – used for display “new” label in survey editor

  • daysNewFor – used to determine how many days to display “new label”

  • description – long description of this node

  • title – short description of this node

  • maxCompat, minCompat - compat level range this node is usable in

  • name – name to use in the <logic uses="XXX.1"/> XML code

  • state: dev, testing, live or closed. Use only live nodes in new surveys

  • version – the version number (1 and upwards). Multiple versions of the same node can exist. Use the highest versioned live one

  • template – string to insert in Builder when creating this node

  • path – filesystem path where this node is defined

  • owner – email address of node creator

  • treeIcon – relative URL to PNG file to be used in the survey editor tree

  • panIcon – relative URL to the PNG file to be used in the survey element menu

  • grouping – the argument listed in display order with group title

  • properties – object mapping property names to descriptions. E.g. for recaptcha node, you can use nodelabel.human to access the result – that’s a property

  • attributes – config attributes on this node; an array of objects:

    • name – the full name including namespace
    • title – attribute name
    • type – one of string, html, int, datetime, email, emails, enum (single enumerated value), expression, set (0 or more enumerated values)
    • values – the possible values for type enum or set
    • description – for humans
    • encrypted – true this attribute supports encrypted values
    • pipeable – true if contents of the node have [pipes] and ${expressions} replaced prior to use
    • required – true if value must be specified
    • defaultValue – default value if not specified

Example URI

GET release.decipherinc.com/api/v1/logiclib
URI Parameters
HideShow
builderOnly
bool (optional) Default: false 

retrieve only those logic nodes usable in builder

base
string (optional) Example: selfserve/53a

survey path to consider as base for survey/client specific nodes

Kinesis Account

Get Kinesis Account Details
GET/api/v1/kinesis/{instance}

Example URI

GET release.decipherinc.com/api/v1/kinesis/
URI Parameters
HideShow
instance
string (required) Example: <server>
Request
HideShow
Body
{
  "instance": "<server>"
}
Response  200
HideShow
Body
{
  "company_id": "101",
  "api_key": "NxgcAZZgSCHKndsSfjzj",
  "instance": "<server>"
}

Get Kinesis Panel Apps
GET/api/v1/kinesis/{instance}

Retrieves list of all kinesis panel-apps associated with given kinesis instance.

Example URI

GET release.decipherinc.com/api/v1/kinesis/
URI Parameters
HideShow
instance
string (required) Example: <server>
Request
HideShow
Body
{
  "instance": "<server>"
}
Response  200
HideShow
Body
{
    "company_id": "101",
    "api_key": "NxgcAZZgSCHKndsSfjzj",
    "instance": "<server>",
    panels: [
        {
            "panel_id": 15",
            "description": "Gardening Panel"
        },
        {
            "panel_id": "16",
            "description": "Gardening Panel 2"
        },
    ]
}

Create Kinesis Account
POST/api/v1/kinesis/{instance}

Example URI

POST release.decipherinc.com/api/v1/kinesis/
URI Parameters
HideShow
company_id
int (required) Example: 101
instance
string (required) Example: <server>
api_key
string (required) Example: NxgcAZZgSCHKndsSfjzj
Request
HideShow
Body
{
  "company_id": "101",
  "api_key": "NxgcAZZgSCHKndsSfjzj",
  "instance": "<server>"
}
Response  200
HideShow
Body
{
  "company_id": "101",
  "api_key": "NxgcAZZgSCHKndsSfjzj",
  "instance": "<server>"
}

Update Kinesis Account
PUT/api/v1/kinesis/{instance}

Example URI

PUT release.decipherinc.com/api/v1/kinesis/
URI Parameters
HideShow
company_id
int (required) Example: 101
api_key
string (required) Example: NxgcAZZgSCHKndsSfjzj
instance
string (required) Example: <server>
Request
HideShow
Body
{
  "company_id": "101",
  "api_key": "NxgcAZZgSCHKndsSfjzj",
  "instance": "<server>"
}
Response  200
HideShow
Body
{
  "company_id": "101",
  "api_key": "NxgcAZZgSCHKndsSfjzj",
  "instance": "<server>"
}

Delete Kinesis Account
DELETE/api/v1/kinesis/{instance}

Example URI

DELETE release.decipherinc.com/api/v1/kinesis/
URI Parameters
HideShow
company_id
int (optional) Example: 101
instance
string (required) Example: <server>
Request
HideShow
Body
{
  "company_id": "101",
  "instance": "<server>"
}
Response  200
HideShow
Body
{
  "status": "ok"
}

Kinesis Panel App

Get Kinesis Panel App Details
GET/api/v1/kinesis/{instance}/panel_apps/{panel_id}

Example URI

GET release.decipherinc.com/api/v1/kinesis//panel_apps/2
URI Parameters
HideShow
instance
string (required) Example: <server>
panel_id
int (required) Example: 2
Request
HideShow
Body
{
  "panel_id": "2",
  "instance": "<server>"
}
Response  200
HideShow
Body
{
  "panel_id": "2",
  "description": "gardening panel",
  "instance": "<server>"
}

Create Kinesis Panel App
POST/api/v1/kinesis/{instance}/panel_apps/{panel_id}

Example URI

POST release.decipherinc.com/api/v1/kinesis//panel_apps/2
URI Parameters
HideShow
instance
string (required) Example: <server>
panel_id
int (required) Example: 2
description
string (optional) Example: Gardening panel
Request
HideShow
Body
{
  "panel_id": "2",
  "description": "gardening panel",
  "instance": "<server>"
}
Response  200
HideShow
Body
{
  "panel_id": "2",
  "description": "gardening panel",
  "instance": "<server>"
}

Update Kinesis Panel App
PUT/api/v1/kinesis/{instance}/panel_apps/{panel_id}

Example URI

PUT release.decipherinc.com/api/v1/kinesis//panel_apps/2
URI Parameters
HideShow
instance
string (required) Example: <server>
panel_id
int (required) Example: 2
description
string (optional) Example: Gardening panel
Request
HideShow
Body
{
  "panel_id": "2",
  "description": "gardening panel",
  "instance": "<server>"
}
Response  200
HideShow
Body
{
  "panel_id": "2",
  "description": "gardening panel",
  "instance": "<server>"
}

Delete Kinesis Panel App
DELETE/api/v1/kinesis/{instance}/panel_apps/{panel_id}

Example URI

DELETE release.decipherinc.com/api/v1/kinesis//panel_apps/2
URI Parameters
HideShow
instance
string (required) Example: <server>
panel_id
int (required) Example: 2
Request
HideShow
Body
{
  "panel_id": "2",
  "instance": "<server>"
}
Response  200
HideShow
Body
{
  "status": "ok"
}

Error testing

Generate error
GET/api/v1/fatal

Generates a fatal error. If error 501 is passed, an “out of memory” error is simulated.

Example URI

GET release.decipherinc.com/api/v1/fatal
URI Parameters
HideShow
error
string (optional) Default: 500 

HTTP response code

Cluster key management

Submit key
POST/api/v1/fed/keys

Called by a member of a multi-server cluster, targetting the cluster master.

Example URI

POST release.decipherinc.com/api/v1/fed/keys
URI Parameters
HideShow
host
string (required) 

The hostname

url
string (required) 

The primary HTTPS url used to call API calls on this server

apikey
string (required) 

The full API key to use to call back into this host

Cluster checkin

Checkin
POST/api/v1/fed/checkin

Called by a cluster member daily as a “keepalive” and to push configuration.

Example URI

POST release.decipherinc.com/api/v1/fed/checkin
URI Parameters
HideShow
host
string (required) 

The hostname

sysinfo
object (required) 

equivalent to output of the sysinfo call

Cluster distributed call

Call distributed
POST/api/v1/fed/call/{hosts}

Replicate this API call among all members of the clusters using their submitted API key. Returns an object with properties error and results. Each host is in either object. The error object maps hostname to an object with two properties: status and message. The results has the API result

Example URI

POST release.decipherinc.com/api/v1/fed/call/hosts
URI Parameters
HideShow
hosts
string (required) 

Host sub-group. Use “all”

fun
string (required) 

API function to call, e.g. rh/users

args
object (optional) Default: {} 

arguments to call the API function with

method
string (optional) Default: GET 

Method

timeout
int (required) Default: 15 

number of seconds to wait for a response

Crypto subsystem status

Get Crypto Status
GET/api/v1/crypto

All of the crypto subsystem calls were added in Decipher 29.

Retrieves the current encryption subsystem status. Returns an object containing:

  • seeded (boolean) has the encryption system been seeded with a pass phrase?

  • unlocked (boolean) has someone entered the passphrase?

Example URI

GET release.decipherinc.com/api/v1/crypto
Response  200
HideShow
Body
{
  "seeded": true,
  "unlocked": true
}

Seeding

Seed with initial passphrase
POST/api/v1/crypto/seed

Example URI

POST release.decipherinc.com/api/v1/crypto/seed
URI Parameters
HideShow
passphrase
string (required) 

set the passphrase. Must be at least 16 characters long.

Modify passphrase
PUT/api/v1/crypto/seed

Re-encrypt all the keys with a new passphrase.

Example URI

PUT release.decipherinc.com/api/v1/crypto/seed
URI Parameters
HideShow
current
string (required) 

current passphrase

passphrase
string (required) 

new passphrase

Unlocking

Unlock
POST/api/v1/crypto/unlock

After restart the crypto service must be unlocked before it can be used. After 5 unlock attempts, the system must be rebooted to continue.

Example URI

POST release.decipherinc.com/api/v1/crypto/unlock
URI Parameters
HideShow
passphrase
string (required) 

passphrase to attempt

Key management

Create
POST/api/v1/surveys/{survey}/key

Get or create the key for this path, prior to writing to the file. Note: the actual key can only be retrieved locally and not remotely. The key returned is a base-64 encoded AES-256 key.

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/key
URI Parameters
HideShow
survey
string (required) 

survey path used for encryption key identification

Response  200
HideShow
Body
{
  "key": "8dTKTMIbR+/y2cK/UcVeWdIJlLo+xQ9GXwwflE8rhyQ="
}

Get
GET/api/v1/surveys/{survey}/key

Get the key for this path. The key must exist.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/key
URI Parameters
HideShow
survey
string (required) 

survey path used for encryption key identification

Response  200
HideShow
Body
{
  "key": "8dTKTMIbR+/y2cK/UcVeWdIJlLo+xQ9GXwwflE8rhyQ="
}

Password encryption

Encrypt
POST/api/v1/crypto/encrypt-password

Encrypt a password to be stored in the survey.xml file. The scope will decide where the encrypted password can be reused. For example if you are uploading files from your surveys via the upload.1 logic node you may want to set the scope to every of your surveys to make it easier for users without the password to set it up. Decipher 29

Example URI

POST release.decipherinc.com/api/v1/crypto/encrypt-password
URI Parameters
HideShow
password
string (required) 

the password to encrypt

scope
string (required) 

either the client directory (selfserve/1234) or a specific survey (selfserve/1234/5678).

Request
HideShow
Body
{
  "scope": "selfserve/5422",
  "password": "setec_astronomy"
}
Response  200
HideShow
Headers
Content-Type: 200
Body
{
  "encrypted": "Q1JZUB8AAAAAAAAAaO6prwsO2K7z0P1RNM2Z2uNDtJuAi8m2xxc2sPLxZNvFKnxTM/TF/e7RgG5L5rCR"
}

Special reports

These ad-hoc reports (normally accessible for staff via https://selfserve.decipherinc.com/admin or your equivalent link) combine administrative data in various ways.

List Special Reports
GET/api/v1/sqlreports

Retrieve a list special reports. The object key is the report name (pass it as {report} below). Description contains an English explanation of what it does. Args will contain optional arguments and their normal default value. Those can be passed in to get a 30-day rather than 90-day report.

Example URI

GET release.decipherinc.com/api/v1/sqlreports
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "app_browser": {
  "args": {},
  "description": "Undocumented"
 },
 "send_detail": {
  "args": {
   "days": "90"
  },
  "description": "Undocumented"
 },
 "supervisors": {
  "args": {},
  "description": "All supervisors"
 },
}

Specific reports

Get Sepcial Report
GET/api/v1/sqlreports/{report}

The report return will be an array of objects with identical keys contained in data and the ordered list of columns as recommended for presentation in columns.

Example URI

GET release.decipherinc.com/api/v1/sqlreports/report
URI Parameters
HideShow
report
string (required) 

one of the report names as retrieved from the report list

args
object (required) 

additional configuration for the report

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "browser_code": "c44",
      "count": 5,
      "app": "theme"
    },
    {
      "browser_code": "c45",
      "count": 1,
      "app": "theme"
    }
  ],
  "columns": [
    "app",
    "browser_code",
    "count"
  ]
}

File dependencies

Get dependencies
GET/api/v1/surveys/{survey}/dependencies

Return the files this survey depends on. Changes to the files will cause the survey to be reloaded. An object is returned with the filename as keys. The values of the object will be null.

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/dependencies
URI Parameters
HideShow
survey
string (required) 

path to survey

Response  200
HideShow
Body
{
     "selfserve/1234/190001/survey.xml": null,
      "hermes/styles/dm.style": null,
}

Languages

List Languages
GET/api/v1/languages

Retrieve a list of all available application languages and any settings configured, where the settings are any of:

  • language Language name

  • territory Language Country / Region

  • code Language identifier

  • decimal_point Decimal delimiter

  • grouping Number of digits to the left of the thousands_sep

  • thousands_sep Thousands separator

  • int_curr_symbol International currency symbol

  • currency_symbol Local currency symbol

  • p_cs_precedes The currency_symbol precedes the value for a positive monetary quantity

  • n_cs_precedes The currency_symbol precedes the value for a negative monetary quantity

  • p_sep_by_space The currency_symbol is separated from a positive monetary quantity by a space

  • n_sep_by_space The currency_symbol is separated from a negative monetary quantity by a space

  • mon_decimal_point Monetary decimal delimiter

  • frac_digits Number of fractional digits to the right of the mon_decimal_point for local currency

  • int_frac_digits Number of fractional digits to the right of the mon_decimal_point for international currency

  • mon_thousands_sep Monetary thousands delimiter

  • mon_grouping Number of digits to the left of the mon_thousands_sep

  • positive_sign The sign for a positive monetary quantity

  • negative_sign The sign for a negative monetary quantity

  • p_sign_posn Sign position in currency (value of 0-4) for positive quantities

  • n_sign_posn Sign position in currency (value of 0-4) for negative quantities

Example URI

GET release.decipherinc.com/api/v1/languages
URI Parameters
HideShow
lang
string (required) 

optional language code; return the information for this language instead of a list of all languages

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "territory": "US",
    "code": "en_US",
    "language": "English"
  },
  {
    "territory": "Japan",
    "code": "ja_JP",
    "language": "Japanese"
  }
]

Theme stats

Get Theme stats
GET/api/v1/rh/themestats

Internal usage only.

Example URI

GET release.decipherinc.com/api/v1/rh/themestats

Get Interviewers

List Interviewers
GET/api/v1/offline/surveys/{survey}/interviewers

Retrieve offline interviewers for the survey.

Return object:

  • interviewers

Example URI

GET release.decipherinc.com/api/v1/offline/surveys/survey/interviewers
URI Parameters
HideShow
survey
string (required) 

path to the survey

active
boolean (optional) 

filter results to just active or inactive interviewers

visible
boolean (optional) 

filter results to only interviewers that are visible on Response Summary or not visible

Response  200
HideShow
Body
{
    "interviewers": [
      {
        "survey_language": null,
        "user_id": 1,
        "description": "developer@decipherinc.com",
        "interviewer_id": "d93eceba",
        "url": "https://selfserve.decipherinc.com/apps/offline/admin/demo%2Fkitchensink",
        "last_respondent_upload_on": null,
        "permission_type": "self",
        "total_completes": 0,
        "valid_completes": 0,
        "access_code": null,
        "active": true,
        "path": "demo/kitchensink",
        "partial_completes": 0,
        "keepalive": false
      },
      ...
    ]
  }

Create Interviewer
POST/api/v1/offline/surveys/{survey}/interviewers

Create a new offline interviewer for the survey.

Return object:

  • interviewer

Example URI

POST release.decipherinc.com/api/v1/offline/surveys/survey/interviewers
URI Parameters
HideShow
survey
string (required) 

path to the survey

description
string (required) 

interviewer description

userId
string (optional) 

beacon user ID of user you would like to create this offline interviewer for

hidden
boolean (optional) 

whether interviewer is shown on Response Summary or not

Request
HideShow
Body
{
   "description": "developer@decipherinc.com",
   "userId": "1",
   "hidden: "false"
  }
Response  200
HideShow
Body
{
    "interviewers": [
      {
        "survey_language": null,
        "user_id": 1,
        "description": "developer@decipherinc.com",
        "interviewer_id": "d93eceba",
        "url": "https://selfserve.decipherinc.com/apps/offline/admin/demo%2Fkitchensink",
        "last_respondent_upload_on": null,
        "permission_type": "self",
        "total_completes": 0,
        "valid_completes": 0,
        "access_code": null,
        "active": true,
        "path": "demo/kitchensink",
        "partial_completes": 0,
        "keepalive": false
      },
      ...
    ]
  }

Get Interviewer

Get Interviewer
GET/api/v1/offline/surveys/{survey}/interviewers/{interviewerId}

Retrieve single offline interviewer for the survey.

Return object:

  • interviewer

Example URI

GET release.decipherinc.com/api/v1/offline/surveys/survey/interviewers/interviewerId
URI Parameters
HideShow
survey
string (required) 

path to the survey

interviewerId
string (required) 

ID of the interviewer you want to retrieve

active
boolean (optional) 

filter result based on interviewers active status

Request
HideShow
Body
{
   "active": "true",
  }
Response  200
HideShow
Body
{
  "interviewer": {
    "survey_language": null,
    "user_id": 1,
    "description": "developer@decipherinc.com",
    "interviewer_id": "d93eceba",
    "url": "https://selfserve.decipherinc.com/apps/offline/admin/demo%2Fkitchensink",
    "last_respondent_upload_on": null,
    "permission_type": "self",
    "total_completes": 0,
    "valid_completes": 0,
    "access_code": null,
    "active": true,
    "path": "demo/kitchensink",
    "partial_completes": 0,
    "keepalive": false
  }
}

Update Interviewer
PUT/api/v1/offline/surveys/{survey}/interviewers/{interviewerId}

Update an interviewer.

Return object:

  • interviewer

Example URI

PUT release.decipherinc.com/api/v1/offline/surveys/survey/interviewers/interviewerId
URI Parameters
HideShow
survey
string (required) 

path to the survey

interviewerId
string (required) 

ID of the interviewer you want to retrieve

interviewer
dict (optional) 

interviewer object with new values for mutable attributes (‘active’, ‘hidden’, ‘description’, ‘survey_language’)

Request
HideShow
Body
{
  "interviewer": {
    "active": true,
    "hidden": false,
    "description": "new_description"
  }
}
Response  200
HideShow
Body
{
  "interviewer": {
    "survey_language": null,
    "user_id": 1,
    "description": "new description",
    "interviewer_id": "d93eceba",
    "url": "https://selfserve.decipherinc.com/apps/offline/admin/demo%2Fkitchensink",
    "last_respondent_upload_on": null,
    "permission_type": "self",
    "total_completes": 0,
    "valid_completes": 0,
    "access_code": null,
    "active": false,
    "path": "demo/kitchensink",
    "partial_completes": 0,
    "keepalive": false
  }
}

Create group

Create Interviewer Group
POST/api/v1/offline/surveys/{survey}/groups

Create interviewers for users in a group for a survey.

Return object:

  • group

Example URI

POST release.decipherinc.com/api/v1/offline/surveys/survey/groups
URI Parameters
HideShow
survey
string (required) 

path to the survey

groupId
string (required) 

user group ID

hidden
boolean (optional) 

whether interviewers are shown on Response Summary or not

Request
HideShow
Body
{
  "groupId": "1",
  "hidden": "false"
}
Response  200
HideShow
Body
{
  "group": {
    "id": "1"
  }
}

Get Offline Summary
GET/api/v1/offline/surveys/{survey}/groups

Download a spreadsheet containing interviewers and data from Response Summary Offline table.

Return object:

  • format

  • interviewers

Example URI

GET release.decipherinc.com/api/v1/offline/surveys/survey/groups
URI Parameters
HideShow
survey
string (required) 

path to the survey

format
string (optional) Default: csv 

format for spreadsheet (currently only ‘csv’ is supported)

exclude
array (optional) 

exclude interviewers that fall under this criteria (e.g. ["beacon", "inactive"])

Request
HideShow
Body
{
  "active": "true",
  "format": "csv"
}
Response  200
HideShow
Body
{
    "format": "csv",
    "interviewers": "\"Interviewer\",\"Status\",\"Access Code\",\"Link\",\"Total Completes\",\"Valid Completes\",\"Uploaded Partials\",\"Latest Upload\"
                    \"developer@decipherinc.com\",\"Active\",\"\",\"https://selfserve.decipherinc.com/apps/offline/admin/demo%2Fkitchensink\",\"0\",\"0\",\"0\",\"\"
                    \"interviewer\",\"Active\",\"\",\"https://selfserve.decipherinc.com/apps/offline/admin/demo%2Fkitchensink\",\"1\",\"1\",\"0\",\"2017-02-16 00:44:28\""
  }

Get Company Types

List Company Types
GET/api/v1/rh/companies/types

Retrieve list of available company types.

Return object:

  • company_types
  • Parameters - None

Example URI

GET release.decipherinc.com/api/v1/rh/companies/types
Response  200
HideShow
Body
{
    "company_types": [
      {
        "id": 1,
        "label": "Research Company"
      },
      ...
    ]
  }

Get Salesforce Connections

Get Salesforce Connections
GET/api/v1/rh/companies/{company}/integrations/salesforce

Get a list of salesforce connections associated with the company, and an object containing information that can be used to integrate a new one. Requires edit permission for the company.

Return object:

  • company (string): Name of the company

  • integration (object)

    • id (string): A unique id used for this company’s salesforce integration
    • enabled (boolean): If the integration is enabled for the company
    • connections (list)
      • id (string): A unique id for this connection
      • salesforce_username (string): The account username in salesforce associated with this connection
      • created_by (string): Decipher username that created the connection
      • created_at (string): Time the connection was created at, in RFC2616 format
      • last_used (string): Time the connection was last used, in RFC2616 format
      • attributes (object)
        • description (string): A description of the connection
        • salesforce_report_folder (string): The id of the report folder containing reports for importing
        • is_sandbox (boolean): If the connection is for a sandbox account
        • is_active (boolean): If the connection is valid and working
      • report_folders (list)
        • id (string): A unique id for the folder
        • name (string): A name given to the folder
    • login (object)
      • origin (string): Location of the external salesforce service to use
      • url (string): Url for beginning the OAuth process to add a new connection
      • sandbox_url (string): Url for beginning the OAuth process to add a new sandbox connection
      • user (string): Token to add to the OAuth url for authentication

Example URI

GET release.decipherinc.com/api/v1/rh/companies/company/integrations/salesforce
URI Parameters
HideShow
company
string (required) 

id of the company

Response  200
HideShow
Body
{
  "company": "Decipher",
  "integration": {
    "id": "8ba6a6af-1fc5-4113-8f8c-28a228e1e708",
    "enabled": true,
    "connections": [
      {
        "id": "958f11d8-e7d9-4106-9649-fb3b3a835c95",
        "salesforce_username": "decipher@example.com",
        "created_by": "hermes@example.com",
        "created_at": "Thu, 13 Aug 2020 20:45:05 GMT",
        "last_used": "Tue, 06 Oct 2020 17:38:36 GMT",
        "attributes": {
          "description": "An example connection",
          "salesforce_report_folder": "EXAMPLEID",
          "is_sandbox": false,
          "is_active": true
        },
        "report_folders": [
          {
            "id": "EXAMPLEID",
            "name": "ReportFolder"
          }
        ]
      }
    ],
    "login": {
      "origin": "https://example.com/",
      "url": "https://example.com/salesforce-integration/oauth",
      "sandbox_url": "https://example.com/salesforce-integration/oauth/sandbox",
      "user": "token"
    }
  }
}

Update Salesforce Connection

Update Salesforce Connection
PUT/api/v1/rh/companies/{company}/integrations/salesforce/{connection}

Updates a connection that is associated with this company. Requires edit permission for the company.

Return object:

  • id (string): A unique id for this connection

  • salesforce_username (string): The account username in salesforce associated with this connection

  • created_by (string): Decipher username that created the connection

  • created_at (string): Time the connection was created at, in RFC2616 format

  • last_used (string): Time the connection was last used, in RFC2616 format

  • attributes (object)

    • description (string): A description of the connection
    • salesforce_report_folder (string): The id of the report folder containing reports for importing
    • is_sandbox (boolean): If the connection is for a sandbox account
    • is_active (boolean): If the connection is valid and working

Example URI

PUT release.decipherinc.com/api/v1/rh/companies/company/integrations/salesforce/connection
URI Parameters
HideShow
company
string (required) 

id of the company

connection
string (required) 

id of the connection

description
string (required) 

Description for the connection

salesforce_report_folder
string (required) 

Report folder id to use for importing reports

is_deleted
boolean (required) 

If the connection should be removed

Response  200
HideShow
Body
{
  "id": "958f11d8-e7d9-4106-9649-fb3b3a835c95",
  "salesforce_username": "decipher@example.com",
  "created_by": "hermes@example.com",
  "created_at": "Thu, 13 Aug 2020 20:45:05 GMT",
  "last_used": "Tue, 06 Oct 2020 17:38:36 GMT",
  "attributes": {
    "description": "An example connection",
    "salesforce_report_folder": "EXAMPLEID",
    "is_sandbox": false,
    "is_active": true
  }
}

Get Salesforce Reports

Get Salesforce Reports
GET/api/v1/surveys/{survey}/campaigns/salesforce/reports

Get a list of reports available to retrieve from the company’s connected Salesforce Integration.

Return object:

  • id

  • connection

  • created_on

  • name

  • description

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/salesforce/reports
URI Parameters
HideShow
survey
string (required) 

path to the survey

Response  200
HideShow
Body
{[
      {
          "id": "00O3h000003NTRPEA4",
          "connection": "c74e22ac-72b6-46dc-b033-ee75ad55e120",
          "created_on": "2020-08-21T17:24:02.000+0000",
          "name": "Leads Report",
          "description": null
      },
      {
          "id": "00O3h000003NTRTEA4",
          "connection": "c74e22ac-72b6-46dc-b033-ee75ad55e120",
          "created_on": "2020-08-21T17:09:34.000+0000",
          "name": "Clients",
          "description": null
      }
  ]}

Get Salesforce Report Details

Get Salesforce Report Details
GET/api/v1/surveys/{survey}/campaigns/salesforce/reports/{report_id}

Get information about a specific report from the company’s connected Salesforce Integration.

Return object:

  • id

  • columns

  • name

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/salesforce/reports/report_id
URI Parameters
HideShow
survey
string (required) 

path to the survey

report_id
string (required) 

ID of the report in Salesforce to pull

Response  200
HideShow
Body
{
  "id": "00O3h00000AG3204FA",
  "columns": [
    "FIRST_NAME",
    "LAST_NAME",
    "TITLE",
    "COMPANY",
    "EMAIL",
    "LEAD_SOURCE",
    "STREET",
    "RATING",
    "OWNER"
  ],
  "name": "Leads Report"
}

Upload Salesforce Report as List

Upload Salesforce Report as List
POST/api/v1/surveys/{survey}/campaigns/{campaign}/salesforce/report

Pull the output from a Salesforce report and upload it as a List to a specific campaign. The ident in the response can be used with the status endpoint to determine the success or failure of the async call.

Return object:

  • ident

  • result

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/salesforce/report
URI Parameters
HideShow
survey
string (required) 

path to the survey

campaign
string (required) 

the id of the campaign to upload the list to.

Request
HideShow
Body
{
  "report_id": "00O3h00000AG3204FA",
  "connection_id": "c74e22ac-72b6-46dc-b033-ee75ad55e120"
}
Response  200
HideShow
Body
{
  "ident": "d3y0k2uf31ruc2ep",
  "result": "ok"
}

Get Salesforce Campaigns

Get Salesforce Campaigns
GET/api/v1/surveys/{survey}/campaigns/salesforce/campaigns?connection_id={connection_id}

Get a list of Campaigns available to retrieve from the company’s connected Salesforce Integration.

Return object:

  • campaigns

    • id
    • connection
    • created_on
    • name
    • description

  • total_campaigns

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/salesforce/campaigns?connection_id=connection_id
URI Parameters
HideShow
survey
string (required) 

path to the survey

connection_id
string (required) 

connection id to use to access Salesforce

Response  200
HideShow
Body
{
      "campaigns": [
        {
            "id": "00O3h000003NTRPEC4",
            "connection": "c74e22ac-72b6-46dc-b033-ee75ad55e120",
            "created_on": "2020-08-21T17:24:02.000+0000",
            "name": "CSAT Campaign",
            "description": null
        },
        {
            "id": "00O3h000003NTRTEA1",
            "connection": "c74e22ac-72b6-46dc-b033-ee75ad55e120",
            "created_on": "2020-08-21T17:09:34.000+0000",
            "name": "Clients",
            "description": null
        },
      ],
        "total_campaigns": 2
  }

Get Salesforce Campaign Details

Get Salesforce Campaign Details
GET/api/v1/surveys/{survey}/campaigns/salesforce/campaigns/{sf_campaign_id}?connection_id={connection_id}

Get information about a specific Salesforce Campaign from the company’s connected Salesforce Integration.

Return object:

  • campaigns

    • id
    • connection
    • created_on
    • name
    • description

  • total_campaigns

Example URI

GET release.decipherinc.com/api/v1/surveys/survey/campaigns/salesforce/campaigns/sf_campaign_id?connection_id=connection_id
URI Parameters
HideShow
survey
string (required) 

path to the survey

sf_campaign_id
string (required) 

ID of the campaign in Salesforce to pull

connection_id
string (required) 

connection id to use to access Salesforce

Response  200
HideShow
Body
{
      "campaigns": [
        {
            "id": "00O3h000003NTRPEC4",
            "connection": "c74e22ac-72b6-46dc-b033-ee75ad55e120",
            "created_on": "2020-08-21T17:24:02.000+0000",
            "name": "CSAT Campaign",
            "description": null
        },
      ],
        "total_campaigns": 1
  }

Upload Salesforce Campaign as List

Upload Salesforce Campaign as List
POST/api/v1/surveys/{survey}/campaigns/{campaign}/salesforce/campaign

Pull the output from a Salesforce campaign and upload it as a List to a specific Decipher campaign. The ident in the response can be used with the status endpoint to determine the success or failure of the async call.

Return object:

  • ident

  • result

Example URI

POST release.decipherinc.com/api/v1/surveys/survey/campaigns/campaign/salesforce/campaign
URI Parameters
HideShow
survey
string (required) 

path to the survey

campaign
string (required) 

the id of the campaign to upload the list to.

Request
HideShow
Body
{
  "sf_campaign_id": "00O3h00000AG3204FA",
  "connection_id": "c74e22ac-72b6-46dc-b033-ee75ad55e120"
}
Response  200
HideShow
Body
{
  "ident": "d3y0k2uf31ruc2ep",
  "result": "ok"
}

References

Generated by aglio on 27 Jun 2021