Skip to main content
Reporting API

Guide for using Culture Amp's Reporting API, covering survey data access, limitations and authentication details.

Jessie Walsh avatar
Written by Jessie Walsh
Updated this week

Who can use this feature?

Available on:

  • All Culture Amp subscriptions that include Engagement or Effectiveness.

Important update: migration to our new survey API

We’re phasing out the Reporting API and replacing it with the new and improved Survey API, which offers more streamlined data export options.

What does this mean for you?

  • The Reporting API can no longer be set up, but existing users will still have access for now. However, we recommend migrating to the Survey API as soon as possible for better data and features.

  • Please share this update with your engineering contact managing your Reporting API service.

Our migration guide is available to help transition your endpoints, and our support team is ready to assist with any questions.


Limitations:

It's important to note a few limitations of the API:

  • It only gives you access to data from surveys with the raw data option turned on.

  • Once a survey is launched, you can't go back and enable raw data.

  • Additionally, please be aware that the API does not anonymize survey data or provide access to de-identified responses.

Authentication

Reporting API requests are authenticated using usernames paired with tokens generated within the Culture Amp platform. In order to generate a token, a user must be assigned the Survey data analyst role.

Once you have the Survey data analyst role assigned to you, generate a token via the below steps:

  1. Open your profile (https://.cultureamp.com/my/profile)

  2. Click Generate in the API Token field

  3. Copy this token and store it somewhere secure - it will only be shown once, and should be treated as you would treat a password

📌 Note: If you lose your token, or think that someone else might have gained access to it, you can regenerate your token by clicking Regenerate in your profile. This will invalidate your previous token.

In order to authenticate your requests to the Reporting API, you must include the following headers on every request: CA-API-Token - your token, generated above. E.g. 2ffd9b7c-5b14-4248-bc3a-db6b25bf09a8

CA-API-Username - the email address of the account used to generate the token. E.g. sally.sample@hooli.com

API endpoints


Survey responses

This endpoint will return a summary of your survey, details about questions on the survey, and completed responses to the survey.

Endpoint

GET

https://.cultureamp.com/reporting_api/survey//responses

Subdomain - your account subdomain. E.g. hooli

Survey ID - the id of the survey to retrieve the responses for. E.g. 57145ed8f4761aff35000e9c

Query parameters

cursor - used to retrieve the next page of responses. See section below for information. E.g. NWNhMmZiMTlhYjVhZTczY2RlNzdkZGU2

limit - maximum number of responses to return in a page. Maximum value is 1000. E.g. 250

start_date - an ISO8601 timestamp. When supplied, only responses submitted after or at this timestamp will be returned. Date filtering is not permitted on snapshot surveys. E.g. 2010-01-01T06:00:00.999+00:00

end_date - an ISO8601 timestamp. When supplied, only responses submitted before or at this timestamp will be returned. Date filtering is not permitted on snapshot surveys. E.g. 2020-01-01T06:00:00.999+00:00

Example cURL request

Here is a sample cURL request using the above example parameters.

curl --location --request GET

'http://hooli.cultureamp.com/reporting_api /survey/57145ed8f4761aff35000e9c/responses?limit=250&start_date=2010-01- 01T06:00:00.999+00:00&end_date=2020-01-01T06:00:00.999+00: 00&cursor=NWNhMmZiMTlhYjVhZTczY2RlNzdkZGU2' \

--header 'CA-API-Token: 2ffd9b7c-5b14-4248-bc3a-db6b25bf09a8' \ --header 'CA-API-Username: sally.sample@hooli.com'

Response schema

A successful request will return a response with status code 200 and the JSON similar to the following example.

{

"survey": {

"name": "Hooli's Engagement Survey",

"status": "closed",

"response_count": 211,

"invited_count": 241,

"type": "engagement",

"created_at": "2017-01-14T05:59:53.753Z",

"launched_at": "2017-01-14T05:59:53.753Z",

"closed_at": "2019-07-03T00:00:00.000+00:00"

},

"questions": {

"hooli.150": {

"code": "hooli.150",

"type": "MultiSelectQuestion",

"theme": "People & Teams",

"factors": ["Teamwork & Ownership"],

"label": "If I weren't in my current team I could see myself contributing to:",

"select_options": {

"5879be9d625f15007e0055cb": "Marketing",

"5879be9e625f15007e0055ec": "Product"

}

},

"hooli.murmur50.PER": {

"code": "hooli.murmur50.PER",

"type": "RatingQuestion",

"theme": "Company Confidence",

"factors": ["Company Confidence"],

"label": "The products and services %ACCOUNT_NAME% provides are as good as, or better than, our main competitors",

"select_options": {}

},

"hooli.murmurdb": {

"code": "hooli.murmurdb",

"type": "RatingQuestion",

"theme": "Action",

"factors": ["Action"],

"label": "I believe action will take place as a result of this survey",

"select_options": {}

},

"hooli.murmur50.COMM": {

"code": "hooli.murmur50.COMM",

"type": "FreeTextQuestion",

"theme": "Comments",

"factors": [],

"label": "Are there some things we are doing great here?", "select_options": {}

},

"hooli.department": {

"code": "hooli.department",

"type": "SingleSelectQuestion",

"theme": null,

"factors": [],

"label": "Department",

"select_options": {

"5879be4f625f15007e001846": "IT",

"5879be4f625f15007e001847": "Sales"

}

}

},

"responses": [

{

"email": "edythe_mertz+011b3@cultureamp.com", "employee_id": 52952,

"submitted_at": "2017-01-14T06:01:01.956+00:00", "answers": {

"hooli.150": ["5879be9e625f15007e0055ec", "5879be9d625f15007e0055cb"],

"hooli.murmur50.PER": 5,

"hooli.murmur50.PER.comment": "This is the most amazing use yet of cross-brand collaboration.",

"hooli.murmur50.COMM": "I can't believe we utilize best of-breed experiences.",

"hooli.department.other_option": "Marketing", "hooli.murmurdb": null,

"hooli.department": ["5879be4f625f15007e001846"] }

}

],

"next_cursor": "NTg3OWJlNWI2MjVmMTUwMDdlMDAxYmY3"

}

Additional information:

  • On adhoc surveys, email and employee_id in all responses will be null.

  • If user did not answer a particular question, the value of the answer will be null, such as on line 71.

  • IDs returned as answers to a MultiSelectQuestion or SingleSelectQuestion correspond to the values in the questions section.

  • Comments left on questions that are not a FreeTextQuestion will appear with the under <question_code>.comment, such as on line 68.

  • If a user fills a SingleSelectQuestion with an “Other option” the value will appear under <question_code>.other_option.

Notes


Cursors and paginated responses

The responses section of the JSON will contain a single page of responses, up to the supplied limit. If a limit is not supplied in the query parameters, it is assumed to be 200.

If there are too many responses to fit on one page, then the value next_cursor will be a string (see line 76). You can retrieve the next page of responses by including cursor=<cursor> in the query parameters of your request.

If the next_cursor value is null, then there are no more responses to retrieve.

For example: If there are 2500 completed responses to a survey within the date range specified with start_date and end_date, with a limit of 1000, the first request will return 1000 responses and a next_cursor.

Using that cursor will return another 1000 responses and another next_cursor.

Using the second cursor will return 500 response and a next_cursor value of null.

Surveys


This endpoint will return a list of all surveys on the account, along with each survey’s name, created/launched/closed dates, status (e.g. draft, scheduled, live, closed, archived), and the names of any programs the survey is part of.

Endpoint

GET https://<subdomain>.cultureamp.com/reporting_api/surveys

Example cURL request

Here is a sample cURL request.

curl --location --request GET 'http://hooli.cultureamp.com/reporting_api /surveys' \

--header 'CA-API-Token: 2ffd9b7c-5b14-4248-bc3a-db6b25bf09a8' \ --header 'CA-API-Username: sally.sample@hooli.com'

Response schema

A successful request will return a response with status code 200 and the JSON similar to the following example.

[

{

"name": "Hooli's Adhoc Survey",

"id": "6dadad6a-728d-413c-aad6-22313dc32c4f",

"created_at": "2017-01-14T06:02:08.487Z",

"launched_at": "2017-01-14T06:02:08.487Z",

"closed_at": null,

"status": "active",

"responses_url": "https://<subdomain>.cultureamp.com /reporting_api/survey/<survey_id>/responses",

"programs": [

{

"name": "New Program",

"id": "438d8e22-4ead-46f3-86ea-19bf9c49b1e5" }

]

}

]

Error responses


The API can return these status codes, along with an explanatory message, when there is an error.

Status Code

Reason

404 - Not Found

Feature is not enabled (talk to your CS Coach); or

Survey ID is incorrect

403 - Forbidden

Token is invalid; or

Email is incorrect; or

User does not have Survey Data Analyst permissions

400 - Bad Request

Raw Data Extracts are not enabled for the requested survey; or

Limit is too high; or

Invalid query parameters

502 - Bad Gateway

Request has timed out. Try setting a lower limit.


💬 Need help? Just reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.

Did this answer your question?