1. Results API Guide
  2. Accessing the Results API

Accessing the Results API

Applies to the following products: 
Questionmark OnDemand
Questionmark Perception
Applies to the following Perception versions: 
Perception 5.7

Access to the Results API is protected using basic authentication. This requires the user to enter the username and password for a Reporting Administrator user (a user with reporting permissions) for the Questionmark account they are trying to access the Results API for. Depending on the client, this username and password will be prompted for in different ways. For information on creating a Reporting Administrator user, see Creating a Reporting Administrator user.

This page includes the following sections:

For information on accessing the Results API via a web browser, please refer to Accessing the Results API via a web browser.

For information on accessing the Results API via a third-party tool, please refer to Accessing the Results API using third-party tools.

The client is required to specify a Perception tenant ID/OnDemand customer ID as part of the URL used to access the Results API. The tenant ID/customer ID, username, and password are then checked and it is determined if the supplied credentials are valid. If they are, the user is allowed on through and the request hits the Results API. If they are not, a response is returned with a 401 Unauthorized header included in it. Most tools will try to log in again when this header is supplied, typically up to three times.

The Results API OData feeds are designed to return specific datum and granular subsets of data. When querying multiple data in a feed, querying multiple feeds simultaneously, or querying against the content in a variable that is not a key field for the feed, the Results API may timeout. Users are encouraged to design queries to use specific key values.

Perception access

To access the Results API for a Perception environment, enter the following URL into your client:

https://<server name>/analyticsodata/<tenant ID>/odata/

...where <server name> is the fully-qualified name (including the domain name) of the server where Perception is installed and <tenant ID> is the name of the specific Perception repository are you trying to access the result data for.

OnDemand access

To access the Results API for an OnDemand area, enter the following URL into your client:

https://ondemand.questionmark.com/<customer ID>/odata/

...where <customer ID> is the customer ID of the OnDemand account you want to access the result data for.

If you are an OnDemand user with the new product portal, please refer to the Users of the new product portal section below for information on the permissions required to access the Results API.

Required permissions

The permissions required to access the Results API depends on the version of Questionmark.

Perception 5.7

In Perception 5.7, an administrator must be a Reporting Administrator user with access to all results in order to access the Results API.

The Reporting Administrator user will need to:

  • be an administrator,
  • have full access to all reports in Questionmark, and
  • have full access to all participant results in Questionmark.

You will need to assign the required permissions to a Reporting Administrator user in order to access the Results API.

To create a Reporting Administrator user:

  1. Log into Enterprise Manager.
  2. Select Administration | Administrators.
  3. Click New administrator.
  4. Fill in the required information for the Reporting Administrator user on the Administrator tab.

    Please be aware that the Profile field should be left blank.

  5. On the Reporting tab, ensure all report type permissions and Access results for all groups are selected.

  6. Click Create. Login to Enterprise Manager with this user to access the Results API.

OnDemand

In OnDemand, an administrator must be assigned the following permissions in order to access the Results API: 

  • Access Results API (found in the Analytics permissions section)
  • Access results for all groups (found in the Reporting permissions section)

By default, the Reporter role includes these permissions. To give an administrator the Reporter role:

  1. Login to OnDemand.
  2. Click People, and then select Users.
  3. Find the desired administrator, and then, under Operations, click edit. 
  4. On the administrator's profile page, select the Reporter role.
  5. Click Save.

The administrator will now be able to access the Results API by following the same instructions in the OnDemand access section above. If you do not want to assign the Reporter role to an administrator, it is recommended that you create a new role that has the Access Results API and Access results for all groups permissions instead of editing an existing role to add these permissions. 

Questionmark recommends that you do not edit any of the default roles that ship with OnDemand as changes to them might overwrite your permissions.

To create a new role with the required permissions:

  1. Login to OnDemand.
  2. Click People, and then select Roles.
  3. Enter a name for the new role in the text field below the existing roles (e.g., Results API user), and then click Add role.
  4. The role will be added at the bottom of the list of the existing roles. Click edit permissions.
  5. In the Analytics section, select the Access Results API permission.
  6. In the Reporting section, select the Access results for all groups permission.
  7. Click Save permissions.

You can now assign the new role to an administrator, giving them the ability to access the Results API.