What can I learn from this page? | Guidance for EAP customers on setting up and using the Reporting API |
Who is this page for? | Account Admins, Survey Data Analyst
|
The information in this guide is intended for customers participating in the Early Access Program (EAP). Our Reporting API is currently in its EAP release, and access is limited to those who choose to opt in. While it's still evolving, rest assured that we're actively refining it to ensure stability.
In this initial version, our primary focus has been on speed-to-delivery (for the purposes of learning about customer needs), and not for extensive features, response times or documentation.
We're really keen to hear your thoughts after using the API. Whether it's about how easy it is to use, any technical bumps you've hit, or ideas for what else you'd like to see, we're all ears. If you'd like to share your feedback, just contact our Product Support Team.
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:
Open your profile (https://.cultureamp.com/my/profile)
Click
Generatein theAPI TokenfieldCopy 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.
|
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,
emailandemployee_idin all responses will benull.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
MultiSelectQuestionorSingleSelectQuestioncorrespond to the values in thequestionssection.Comments left on questions that are not a
FreeTextQuestionwill appear with the under<question_code>.comment, such as on line 68.If a user fills a
SingleSelectQuestionwith 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.
|
Response schema
A successful request will return a response with status code 200 and the JSON similar to the following example.
|
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 |