Docs
Go to Conductrics.com →
  1. Conductrics Surveys

Survey Reporting API

Programmatic access to survey response data, for integration with internal systems, etc

It's often sufficient to view survey responses in the Conductrics Admin (see Survey Reporting), but the Survey Reporting API discussed on this page is available if you need to integrate your Conductrics Surveys with other systems.

This Survey Reporting API is part of the Reporting API, which is one of our Admin APIs.

Please reach out to Conductrics if you have questions!

🚧

Please use caution if your surveys prompt visitors to provide any sort of information that could be considered private or personal. Even if nothing in the survey is technically "PII" or restricted legally, we encourage you to use discretion. Please consider retaining the smallest subset of survey response data that is necessary for your actual business requirements.

Fetching Survey Responses

You can get a list of survey responses, which contain individual answers to each survey question.

What you'll need:

  • An API Key for the Conductrics Admin API, which you can get from the Settings > API Keys / Info page in the admin. The API Key will have an admin- prefix. You can generate a new API Key there if you'd like to have one especially for getting survey responses.
  • The API Endpoint URL for the Admin API, also from the Settings > API Keys / Info page. If you are using a private Conductrics environment, this URL is specific to your install and likely contains your company name.
  • Your Conductrics account code, also from the Settings > API Keys / Info page. The account code will have an ac- prefix.
  • The Survey Agent's API Code, which you can get by navigating to the survey's main page in the Conductrics admin, then grabbing it from your browser's URL bar. The Agent's API Code will have an a- prefix.
  • The Reporting Data Pool that you would like survey responses for. At this time the available reporting pools for Surveys are p for Production, or q for QA. These correspond to the "Data Sets" toggle at top right in our Admin UI.

To get a list of survey responses, issue a GET request to a URL like the following, substituting your account info above (this assumes the Agent API Code for the survey is a-abc123xyz):

https://your-api-url.conductrics.com/admin/ac-yyyyyyy/qual/a-abc123xyz/responses?pool=p

📘

Providing Your API Key

You also need to provide a valid admin-xxxxxxxxx API key, either as a query parameter called apikey or as a HTTP header called x-conductrics-apikey.

👍

See below for some additional URL parameters you can provide for filtering, paging, and so on.

Conductrics will respond with a list of items like the following:

{
  "status": 200,
  "data": {
    "items": [
      {
        // unique identifier for the survey response
        "rid": "qs-1674692xxxx-wu2KcQiyyyy",
        // date/time that the survey response was submitted
        "ts": 1674692259,
        
        // answers to the survey questions
        // (see also 'values_expanded' below, probably more convenient for display purposes)
        "values": {
          // for NPS and other survey questions that collect a numeric value
          "sf_xxxxxxx123": 9,
          // for "pick one" or "pick multiple" style survey questions
          "sf_yyyyyyy456": [
            "an-ZbW8" // unique identifier for the answer/choice the visitor selected
          ],
          // for survey questions for the visitor can provide ad-hoc text/comments
          "sf_zzzzzzz789": "My favorite song on the new album is A&W!"
        },
        // answers to the survey questions, with 
        "values_expanded": {
          // for NPS and other survey questions that collect a numeric value
          "sf_xxxxxxx123": 9,
          // for "pick one" or "pick multiple" style survey questions
          "sf_yyyyyyy456": [
            "Electronic"
          ]
        },

        // visitor traits that were active at the time of submission
        // (see also 'traits_expanded' below, probably more convenient for display purposes)
        "traits": [
          "ua/os:m",
          "cust/tier:g"
        ],
        "traits_expanded": [
          // any built-in Visitor Traits active at the time of submission
          {
            "t": "geo/dm:x",
            "t_name": "Is/Not Mobile",
            "v_name": "Is Mobile OS"
          },
          // any Custom Visitor Traits active at the time of submission
          {
            "t": "cust/tier:g",
            "t_name": "Member Tier",
            "v_name": "Gold"
          },
        ],

        // selected variations for any associated ("Linked") A/B tests
        // (see also 'aa_expanded' below, probably more convenient for display purposes)
        "aa": {
          "a-my-linked-test": "B" // selected variation at time of submission
        },
        "aa_expanded": [
          {
            "a": "a-my-linked-test",
            "c": "B",
            "a_name": "My Linked Test",
            "c_name": "B Variation"
          }
        ],
      }, // end of survey response

      // ... additional survey response items ...
    ]
  },

  // Additional information about the survey itself
  "survey": {
    "code": "su-xxxxxxxxx",
    "name": "My First Survey",

    // for each survey "field" (question)
    "fields": {
      "sf_xxxxxxx123": {
        "name": "NPS",
        "title": "How likely are you to recommend us?",
        "type": "rating-dots"
      },
      "sf_yyyyyyy456": {
        "name": "Music",
        "title": "What type of music do you like?",
        "type": "checks"
      }
    }
  }
}

Response Item Contents

Each survey response item represents one survey submission.

Here's what's included for each survey response item:

  • rid - An identifier for the survey response (starting with rid). See callout below.
  • ts - The date/time of the survey submission, as a Unix-style timestamp (seconds past Jan 1, 1970).
  • values - A map of name/value pairs for the visitor's "answers" for each survey "question". The data type of each value (that is, each answer) will vary depending on the type of question.
  • values_expanded - This is also a map of name/value pairs for the visitor's "answers" for each question, but with the visitor's answers in a more convenient form for display. The main difference is you get the "friendly name" for answers to questions where the visitor is choosing from a list of predefined answers (such as "Pick One" and "Pick Multiple" questions).
  • traits - Map of trait types/values for any visitor traits that were enabled and present for the visitor at the time that the survey was submitted.
  • traits_expanded - This is also a map of trait types/values present at the time that the survey was submitted, but with the "friendly names" which is likely more convenient for display.
  • aa - Map of variation selections for any "associated agents" (also known as "Linked A/B Tests" in the admin) that had been selected at the time of the survey response. If the survey doesn't have any "linked" A/B tests, this will be an empty object.

After the response items, some additional information is provided about the survey itself:

  • code - The internal identifier for the survey, which is different from the agent code that you provided in your GET request.
  • name - The friendly name for the survey.
  • fields - Map of the survey's "fields" (aka questions).

For each of the fields, you get the question's unique identifier (with sf prefix), plus:

  • The friendly name for the field/question as it appears in the Conductrics admin
  • The title of the question, as shown in the survey as it appears on your pages
  • The type of the question, such as ratings-dots for NPS-style questions, radios for "Pick One" style questions, checks for "Pick Multiple" style questions, select for "Dropdown" questions, or text for questions where the visitor can type in their own comments/text. Contact Conductrics if you need the full list.

Optional URL Parameters

You can provide some additional parameters when fetching a list of survey responses:

  • rows_start - Index position to start at for "paging" purposes (zero-indexed). Defaults to 0 if not provided.
  • rows_max - The maximum number of rows (response items) to return. Defaults to 1000 if not provided. Note that the API will return an error if you try to fetch more than 1000 items at a time.
  • sort_dir - Controls the sort order of the items. Provide sort_dir=desc if you want the most recent items first. Defaults to asc if not provided (oldest responses first).
  • dateFrom - Use to specify that you only want responses since a given date/time. Provide the date as a Unix-style timestamp (seconds past Jan 1, 1970).
  • dateThru - Use to specify that you only want responses up to a given date/time. Provide the date as a Unix-style timestamp (seconds past Jan 1, 1970).
  • field_values - Use to filter by survey responses where the visitor provided a particular answer to a survey question. Provide as name/value pairs, such as field_values=sf_wmYEfIL31d:10 for just those responses that answered "10" for a numeric-style question. You can get the sf codes from the survey-level info returned by this API call (see above). Separate multiple name/value pairs with commas. If you provide multiple conditions for the same field, they treated as "OR" conditions, so you could use sf_wmYEfIL31d:9,sf_wmYEfIL31d:10 if you wanted responses where the visitor answered 9 or 10.
  • trait_values - Use to filter by survey responses where the visitor had a given built-in or Custom Visitor Trait at the time of the survey response, such as &trait_values=cust/tier:g.
  • choice_values - Use to filter by survey responses where the visitor was selected for a given variation for a "Linked" A/B test at the time of the survey response, such as &choice_values=a-abcdef123:B if you wanted responses for visitors that got the "B" variation for fictitious agent a-abcdef123.
📘

If you are pulling survey responses for display in another system, you may want to make the rid available to your internal users, in case anyone needs to "look up" or delete the survey response in the Conductrics Admin (using the "Lookup by ID" field on the Survey's "Responses" page).

Getting Survey-Level Stats

If you need basic stats about your survey, such as what's shown on the Activity Report for the survey agent (number of visitors that were shown the survey, response rate, and so on), use the decision-stats endpoint as discussed in the "Activity Report Data" part of the Reporting API page.

The survey agent's B variation will correspond to the visitors that were offered the survey, with the A variation reserved for the visitors that were not offered the survey. So, if the "Visitor Survey Rate" under Survey Options is 20%, you would expect about an 80/20 split between A and B, respectively.

Other Options

Instead of using the Survey Responses API (described above), you could consider:

Updated about 1 year ago