Skip to main content

Decipher Support

All the topics, resources needed for Decipher.


FocusVision Knowledge Base

Generic API Call


You can use the Logic Library to suspend a survey and execute an API call via HTTP/HTTPS to a remote server.

This can be done using either the "API Integration" element in the Survey Editor or the "api" logic node in the survey XML.

Note: Using the Decipher API requires users with shell access to whitelist survey URLs. Contact your Project Manager or the Decipher Support team to initiate.

Using the Survey Editor  

To add an API Call using the Survey Editor, click "+ Add Survey Element" under the staging area:


In the Element Library, click "Custom" and select the "API Integration" element. Then click "Insert":


The new element will appear in the staging area, where you can configure the API call parameters:


URL: The base URL on the remote endpoint.

Method: The API call type. Can be set to GET, POST, PUT, or DELETE.

Parameters: The call parameters.

Data:  Any additional payload data.

Using the XML

There are two steps you will need to follow when formatting any API call:

  1. Create a variable that will define the call parameters. Call parameters include what gets passed in the URL (in the GET request).
  2. Write the following exec code, specifying alabel for your API call, along with your preset variable name (api:params) and its URL (api:url):
     <logic uses="api.1" label="xxxx" api:params="yyyy"


The following parameters can be passed using the API logic node:

Attribute Description
api:url This attribute is required and is the base URL to access. The hostname must exist in the api.txt file located in the company directory (selfserve/XXX) or be white-listed within the api.1 logic node.
api:params This attribute is optional. It is the name of a variable that contains the URL parameters and must be a dictionary. For example, if you specify api:params="weather_data" and you've run the code weather_data = {"q": "Copenhagen", "when" : "yesterday"}, then the API call will have ?q=Copenhagen&when=yesterday added to it, along with any special characters.
api:data This attribute is the same as api:param , but uses large data sent in the body of a HTTP POST request.
api:method This attribute specifies the call method. It can be set to GET (default), POST, DELETE, or PUT.
api:headers This attribute is optional. It allows you to pass through custom headers for your call.

Tip: The Logic Library is continually growing and new logic nodes are being added all the time. If you are looking for more functionality with your call, contact your support team to inquire about development of new custom logic nodes for specific API calls.

Once you execute the code above, your survey will be suspended and you can check your variable name on the next page for the HTTP status code.

Interpreting Call Results

To determine whether your API call was successful, you will want to check your node:status and node.r values. The node:status value will be your HTTP status code. If your API call is successful, you should see a status code of "200" here. If the server responds with any other code, there are likely errors in your call; for example, an invalid URL will result in a  "500" status code.

If you receive an error code, you will want to check both your logic syntax and the results of the call.

Note: If you are running simulated data, node.status will return 500.

The node.r value will be the response value of your call. If the API call returned JSON data, this is automatically decoded. Otherwise, you should see raw text here. If your call was successful, you will not need to do anything; the request and response will be logged automatically.


If you wanted to open a page in your survey that showed the weather in respondents' current locations, you might use the following code (where the api:url is Open Weather's weather map webpage and q is the respondent's response to "q" - a survey question asking them "In what city do you currently reside?"):

weather_data = dict(q=city.val)
<logic uses="api.1" label="weather" api:params="weather_data"
if weather.status == 200 and weather.r["cod"] == 200:
  p.temperature = str(weather.r["main"]["temp"] - 273.15)
  p.temperature = None

Each API may have a different way of returning errors, and OpenWeather will have a "cod" field in place of the "node:status" value with either "200" or another status code. Similarly, instead of "node:r", this call will show The weather.r as will be the result.

Note: OpenWeather also returns the temperature in Kelvin, rather than Fahrenheit or Celsius.

  • Was this article helpful?