Forsta Surveys REST API

The Forsta Surveys REST API is the tool for automating your workflow with the Forsta Surveys platform. It enables you to efficiently send and request resources to and from any project you are working on using a collection of Forsta Surveys-specific endpoints and call parameters.

Registered Forsta Surveys users can access the API via web calls, or via a Python library package that, once installed, enables you to integrate with the Forsta Surveys services you have access to.

Whether accessing the API via a web call, or through the Forsta Surveys Python Package, you will need to generate an API key for your user.

1:  Generating an API Key

In order to access the Beacon API externally, you will need to generate an API key for your user through the Portal. To generate an API key from the Portal, click your profile image / avatar and select "API Access".

This will take you to the API access page listing all users who have generated API keys.

Any user listed on this page will also have their public key displayed. Note that the public key alone is not enough to make Beacon API calls. Each user needs their full key that only they have access to in order to make Beacon API calls. To create a brand new key for you user, you can select the "Create new API key" option. This take you through several steps before you get your key.

First, you need to specify the user for which you want to generate the key. You can either enter the username of the user or input self if you are generating a key for yourself:

Note:  Only staff or supervisor users can specify a username other than self. Supervisor user accounts can create API keys for non-staff user accounts within their company.

Next, enter any desired restrictions or click "OK" to continue:

You will then receive a 64-character API key that you can use to authenticate your API calls:

The API key consists of two parts. The first 32 characters are your public key that display on the main API page, while the second 32 characters are your private key that will never be listed anywhere. In order to make API calls, the full 64 characters must be passed through.

Note:  Be sure to copy the full key and keep it in a safe place. Do not share this key with anyone. The API key logs and represents your user when making API calls, so anyone who has it can access projects as if they were you.

Once you grab your API key, your user will be added to the list of available keys on the main API page.

This page will display only your public key, so you won’t be able to grab the full key from this page. If you no longer have your full key, you have the option to generate a new key by clicking the "rekey" option. You also have the option to delete the API key for your user, if you no longer wish to use it.

2:  API Call Permissions

The API key will allow you to execute only the API's that your user account has permissions to run. For example, if a certain user has "View Only" access to a project, they will not be able to access a 'Data Edit' API call. Likewise, if a user is not a Supervisor, they will not be able to execute an API call to retrieve a list of all users for a company.

While a user with a valid key will be able to execute any API call, if they attempt to execute a call they do not have permission to run, they will receive a "403 INVALID AUTHORIZATION" error code instead of the expected result.

The following is an example of the '403' error code response:

curl --header 'x-apikey: 6xd513ar9uvh4vw05de41dkc08h60c6xp6xj4eb3ma7hkdenejcp3ghxkwrmr8se' ‘https://emea.focusvision.com/api/v1/rh/users’
{
"$error": "you cannot do this",
"$code": 403,
"extra": null
}

Note:  See Create and Manage Users to learn more about user permissions within Forsta Surveys.

3:  Accessing the API

3.1:  From a Linux System

3.1.1:  Installing the API Python package

To access the API, you will first need to download and install the Forsta Surveys API Python Library package. For users with their own private cloud servers, the API Python library is installed by default, and can be accessed via the shell.

If you are accessing the API via some other Linux system, you can install the Forsta Surveys API Python library using the following command:

sudo pip install decipher

This Python library includes a script named "beacon" that can run from the command line and is used to easily connect with the API.

Once the library is installed, you can type beacon into your command line to view its usage details:

user@domain:~$ beacon
Usage:
beacon [options] <verb> <resource> [arg=value...]
Verb is one of:
get    -- list resources
post   -- create new resource
put    -- update existing resource
delete -- delete or retire existing resource
login  -- interactively define an API key and host
rekey -- rekey your current secret key and update the config file

Extra arguments are decoded as JSON objects/arrays if they start with { or [

Options:
-v verbose (show headers sent & received))
-t display output as an aligned text table
-x display output as IBM JSON XML
-p display Python code required to make the call
-s <section> use a different section in the /home/user/.config/decipher file than 'main'
-V <version> use a different API version

3.1.2:  Authentication and Authorization

The Forsta Surveys API will only respond to authorized users. To become authorized, you must first generate an API key that will be authenticated by the system.

Note: For Forsta Surveys Cloud customers, authentication happens automatically with your shell credentials if running the commands via the command line. There is no need to login with the steps below.

Type beacon login into your shell terminal to view the methods for authenticating with the system:

How do you want to authenticate?
1. Enter the 64-character API key (valid until deactivated)
2. Enter your username/password (temporary login)
3. Enter a long code (visible on the API key page)
q. Quit
Select 1, 2, 3 or q: 1

API key authentication

Using this method, you only need to authenticate once. Once you provide your API key, it will be saved under your Linux user’s config settings, and it will be automatically provided when you use the beacon command.

Example:

API KEY: *provide your 64 character key here*

Enter your host, or press Enter for the default v2.decipherinc.com
Host: emea.focusvision.com
Testing your new settings...
Looks good. Settings were saved to the file /home/user/.config/decipher

As illustrated above, when providing your API key, you will be asked to enter the "Host" for which it has been generated. This is the domain that you use to log into Forsta Surveys. For example, if you use https://v2.decipherinc.com/login to access the platform, your host name will be "v2.decipherinc.com".

Username / password login

This method allows you to login with your Forsta Surveys username and password, and will generate a temporary API key for you. Similar to the API key authentication method, you need to specify the host name of the server where you wish to log in.

Example:

Enter your full username (email address)
Username: [e-mail]
Enter your password
Password: password
Enter your host, or press Enter for the default https://emea.focusvision.com
Host: emea.focusvision.com
Testing your new settings...
Acquired a temporary session key. It will be expire after 25403883 minutes of idle time.
Looks good. Settings were saved to the file /home/user/.config/decipher

Note: The above method only creates a temporary key for your current session.

Generating a temporary key

Selecting this option allows you to login with a temporary key generated from the API page in the Forsta Surveys application.

Clicking the "generate temporary key" hyperlink will give you a new API key. You can then input that key when prompted.

Example:

Temporary Key: *your temporary key here*
Testing your new settings...
Looks good. Settings were saved to the file /home/pagov/.config/decipher

Note:  The recommended way of authentication when using the Forsta Surveys REST API is to use a permanent API key.

4:  Executing API Calls

Once you are connected to the Forsta Surveys API, you can execute API calls directly from the command line, via Python scripts, or using a web call.

Note:  The execution of API calls is limited by survey and by user. Each user is allowed to run just one call at a time for a survey. Additionally, no more than three calls can be active on one survey at any given time.

4.1:  From the Command Line

The beacon script lets you run API calls directly from the command line. Depending on the API call, you can use the beacon script to execute GET, POST, PUT or DELETE requests.

Example GET:

beacon get rh/users

The above command uses a GET method to return a list of all users for a specific company or server.

Note: This command requires the user to have a Forsta Surveys Cloud account.

Example PUT:

beacon put rh/users/4504 active=false

The above command uses a PUT method to change the active property to false, thus disabling the user.

Example POST:

beacon post surveys/selfserve/214e/180100/sst count=200 qualified=true

The above command uses a POST method to run simulated test data for the selfserve/214e/180100 project. The "count" argument being passed through sets the number of test data to run, while the "qualified" flag tells the system to submit mostly qualified runs.

Example DELETE:

beacon delete rh/apikeys/aj8vzu9ze9r6nv7yyqy3g5u0970960qfaj8vzu9ze9r6nv7yyqy3g5u0970960qf

4.2:  Via Python Scripts

From the command line, you can also pass the -p flag through a beacon command to review the corresponding Python syntax. You can then place that syntax in a Python script file to automate the execution of an API call.

Example:

beacon -p get rh/users select=id,login,fullname,last_login_where sort=-last_login_where limit=10

The above command will not execute the API call, but will instead provide you with the following syntax:

from decipher.beacon import api
result = api.get('rh/users', sort="-last_login_where", limit="10", select="id,login,fullname,last_login_where")
print result

You can then paste the above output directly in a Python script.

4.3:  Using Web Calls

You can also access the Forsta Surveys API via a web call utility, as you would any web-based API. One such utility is cURL, which is used for all the following examples.

Note: General Information about cURL can be found on curl.se.

4.3.1:  Authentication

All web calls must include your API key in the x-apikey header.

Note: The username / password authentication method is not available when using web calls.

Example 1:

curl --header "x-apikey: API_KEY" 'https://v2.decipherinc.com/api/v1/meta'

The above command is used to access a list of all the currently implemented API endpoints in Forsta Surveys.

Note:  You need to surround your API call URL in single quotes, in order to ensure that any special characters get escaped properly.

Note:  If using other methods to make a web call, you need to make sure that they are able to pass in the x-apikey header as part of your request.

4.3.2:  Executing Web Calls

The main difference between using the beacon package and executing web calls is that web calls will need the full URL to the API endpoint you wish to access. For example, running the users API call will require you to add extra information to the API endpoint definition.

beacon Package Example:

beacon get rh/users/4504 active=false

cURL (Web Call) Example:

curl --header "x-apikey: API_KEY” https://v2.decipherinc.com/api/v1/rh...4?active=false

Apart from adding the host name of the server where your project is situated, you also need to add in api/v1 as part of your API endpoint reference, to explicitly tell the system to access the API.

4.3.3:  Web Request Examples (Using cURL)

Example GET:

The following command can be used to test out the “Hello Service” endpoint to test out the API system:

curl --header "x-apikey: API_KEY" https://v2.decipherinc.com/api/v1/he...name=FunFunFun

The example above will return a JSON object as a response:

{"ok": "1", "hello": "FunFunFun"}

Example POST:

Reproducing the same POST command executed earlier with the beacon package will require the following syntax:

- curl --header "x-apikey: API_KEY" -X post  https://v2.decipherinc.com/api/v1/surveys/selfserve/214e/180100/sst?count=200&qualified=true

Note that when passing in additional parameters to the API call, you need to add them as URL parameters to the end of the API endpoint. The first parameter you add should be prefixed with ? (?count=200), while any additional parameters should be prefixed with & (&qualified=true).

Note: cURL commands default to using the GET method. To specify a different request method, you must use the -X flag.

Example POST With Data:

Some API calls require you to pass data back through to Forsta Surveys. For example, data edits / imports done through an API call may require you to pass the data to import through in JSON format. When using JSON, you must make sure you pass through the correct content type and use the proper syntax, which includes adding double quotes around the various items within the JSON object:

curl -X POST -H 'Content-Type: application/json' -H "x-apikey: MY_API_KEY" 'https://v2.decipherinc.com/api/v1/su...0100/data/edit' -d '{"data": [{"Q1": 1}]}'

In the above cURL command, several modifiers are used to pass through the information needed to successfully execute the API call.

First, the -X flag is used to specify which method to use for the API call. Then, two -H flags are included - one to add multiple headers to the request. The x-apikey header will hold the API key, and the Content-Type header tells the system that the information will be sent over in a JSON file format. Meanwhile, the -d flag is used to pass through the actual data, and it is followed by the JSON object that contains what is needed to send to the API.

Note: As previously mentioned, any API web call method you use should be able to support the above functionalities, which include adding multiple headers, the ability to specify a web call method (GET, POST, PUT, and DELETE), and the ability to pass in data objects as part of the call.

5:  Forsta Surveys API Python Library Page

Visit the Forsta Surveys API Python package page for more details on the Forsta Surveys API Python library.

6:  Full Forsta Surveys API Endpoints List

Visit the Forsta Surveys API Documentation site for a list of all current and future API resources available with the Forsta Surveys REST API.

7:  Response Codes and Error States

The following HTTP response codes are returned when making a request to the Forsta Surveys API:

Code	Description
200	SUCCESS Your data is in the response body.
401	INVALID AUTHENTICATION Your API key is invalid, expired, or not valid from this IP address or for this action.
402	PAYMENT REQUIRED You have exceeded your available 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 resource that does not exist.
405	METHOD NOT ALLOWED You tried to perform an action that was not allowed (e.g., delete something that does not support deletion).
429	TOO MANY CONCURRENT REQUESTS Please wait a moment and try your request again.
501	NOT IMPLEMENTED Resources do not implement this method. Are you using GET / POST / PUT / DELETE?
400	OTHER Something else went wrong (e.g., the survey cannot be loaded due to an error).

Note: The "402" response code is not currently utilized.