Who can use this feature?
Available on:
All Culture Amp subscriptions that include Engagement or Effectiveness surveys with raw data enabled.
The Survey API is part of the Culture Amp API, providing one-way outbound access to raw data from surveys that have the Raw Data Extract setting enabled. This guide will walk you through setting up the Survey API, understanding its scope, and retrieving survey data. Refer to the scope of available survey data section for data scope and constraints of available raw data served from this API. You can also view available data at any time via our API documentation.
To follow these steps, you'll need access to your account's API credentials and assistance from a developer for technical implementation.
Setting up the Survey API
Enable Raw Data Extract for surveys
Before retrieving data from the Survey API, ensure your surveys have the Raw Data Extract setting enabled before launching the survey. This setting can only be enabled by an Admin user and cannot be applied retroactively. Verify it during the survey creation process.
Add API credentials
To access survey data through the API, you’ll need the Account Admin role. Credentials are generated within your account's Admin Settings.
Follow these steps to add credentials:
Log in as an Account Admin.
Click Settings in the top-right navigation menu.
On the left-hand side, click API under Admin Settings .
Select Create API Credentials and follow the prompts.
Toggle on Read RDE-enabled survey data to include access to raw survey data.
Your credentials consist of a Client ID and Client Secret which are used to authenticate.
For further details, visit our getting credentials documentation.
Using API credentials
Once you've created your credentials, share them with a trusted developer in your organization. The Client ID and Client Secret is needed to authenticate with the API.
To authenticate, follow the steps outlined in the Authentication Guide of the API Developer Portal.
Querying the API
Once authenticated, you have the option to retrieve survey data through various survey API endpoints. Here are the common tasks and endpoints you'll use.
Retrieve survey list and survey IDs
Query the API by first retrieving the list of all surveys in your account with metadata on each.
This can be done by making a request to the ‘List surveys’ endpoint:
Note that the Raw Data Extract setting constraint does not apply to this endpoint.
Data from this endpoint will also detail whether each survey listed is available for raw data extraction (see section on understanding confidentiality protections for more information).
Retrieve desired survey metadata, question or response data.
Using Survey ID as a parameter in the URI enables you to:
Retrieve survey metadata from an individual survey (filtering).
Retrieve a survey’s questions and their configuration from the questions endpoints.
Retrieve a survey’s responses and answers included in each from the responses endpoints.
You can also filter to individual questions or responses in a survey by including a question or response ID as parameters to filter on.
See the developer portal documentation for more information on querying.
Understanding confidentiality protections
Data served via the Survey API adheres to strict confidentiality protections. Surveys must have the Raw Data Extract setting enabled at time of launch to be retrievable via the API.
You can identify which surveys have this setting configured directly from API responses served from the ‘List surveys’ endpoint.
https://docs.api.cultureamp.com/reference/list-surveys
Survey metadata returned from this endpoint will include the
rdeEnabledfield which must have the valuetruereturned against a given survey for its data to be accessible via other survey API endpoints.If a particular survey returns a
falsevalue for this field, it isn’t accessible from the API and attempting to retrieve its data will trigger an error response.
Keep in mind that the Raw Data Extract setting can’t be enabled after a survey is launched.
Scope of available survey data
Keep in mind the API Developer Portal is the source of truth for detailed information on this API and data it serves.
In scope
Item | Notes |
Survey type | All survey types are in scope of data served.
Includes:
|
Workflow | All survey workflows are in scope of data served.
Includes:
Note that ‘continuous’ workflow surveys will populate with null values for certain fields (see below section on data behaviours for more information). |
Kiosk mode | Surveys launched in kiosk mode are in scope of data served. |
Attribution | Both attributed and unattributed survey data is in scope of data served.
Note that ‘unattributed’ surveys will populate with null values for certain fields (see below section on data behaviours for more information). |
Survey status | Includes active and closed surveys.
Deleted or pre-launch (draft) surveys are not in scope of data served. |
Out of scope
Item | Notes |
Factors and sections data | Excluded in data served from version 1 of the Survey API.
Factors and Sections will be included at a later point in version 1.1 as an additive change. |
Aggregated survey data | For example aggregate engagement scores at team or department level.
Not in scope of data served. |
Quant or calculated survey data | For example participation rate or correlations used in driver analysis.
Not in scope of data served. |
De-identified survey data | The API has no ability to de-identify or anonymise data captured from confidential surveys.
Not in scope of data served. |
History and freshness of available survey data
Item | Notes |
Survey data history | All historic survey data in your account is available from the Survey API, providing the survey was launched with the raw data extract setting configured. |
Freshness of data served | Data served from the API is continuously updated automatically.
Changes to data in the platform are reflected in the API where applicable within 20 minutes.
See the ‘processedAt’ field in for details on when the data was last updated to the API. |
Additional data behaviours and constraints
Unattributed surveys
For unattributed surveys, employee_id and surveySubmittedBy in all responses will be null.
Surveys launched multiple times
The following fields all serve the ‘last updated' datetime value from the survey. For example, if a survey was launched multiple times, only the most recent ‘launchedAt:’ date will be served:
launchedAtclosedAtcommunicatedClosedAtcreatedAtupdatedAt
Continuous workflow surveys
Surveys where workflow: "continuous" have no close dates. closedAt will be null in responses for this workflow type.
Deleted surveys, questions and responses
Item | Notes |
Deleted surveys | Not available from any endpoint once a survey is deleted. |
Deleted questions | Continue to be available from the ‘List’ and ‘Get’ Questions endpoints.
Deleted questions will have a deleted value in the ‘status’ field. |
Deleted responses | Not available from any endpoint once a Response is deleted. |
Select option questions size limit
In responses served from the questions endpoints, ‘Select Options’ are truncated to a maximum of 500 per question.
Common use cases
The survey API is a self-serve feature that can be used flexibly in a variety of powerful use cases.
Keep in mind that it is not a connector or integration service and the API does not have the ability to natively connect to other software systems out of the box.
Data retrieved from the API can be transferred however into other systems programmatically with the assistance of developers.
Some examples of use cases include:
Bespoke analysis on raw survey data sets. This might include correlation analysis, text mining or NLP, sentiment analysis, quartile analysis.
Combining survey data with other internal data sets for new insights. Often this is used to link employee engagement to financial, productivity, operational or adjacent HR data.
Existing BI or Reporting programs which can be further enriched and enabled with raw survey data. This also includes running custom reporting on this data based on your organisation’s requirements providing the right data engineering and analytics resources are available.
Surfacing survey data into other systems where required. For example transferring a candidate survey’s responses into a candidate management system to view feedback in each response against recruiters.
Retrospectives on particular surveys and their questions to understand how the survey was designed as part of optimisation or experimentation in survey programs.
Audits of surveys run in the account based on survey metadata to understand what has launched historically, owners of each survey and other descriptive information.
FAQs
Where can I find survey factors and sections data?
Where can I find survey factors and sections data?
We're working on adding new API endpoints for factors and sections data in the coming months.
Do I need an engineer’s help to use the API?
Do I need an engineer’s help to use the API?
Yes, the API is best suited for technical users. It’s not recommended for non-technical stakeholders as misuse can pose risks to customers.
Does the API anonymize or de-identify data?
Does the API anonymize or de-identify data?
No, confidential survey data cannot be accessed through the API.
Does the API provide aggregated survey or reporting data?
Does the API provide aggregated survey or reporting data?
No, aggregated data like Engagement Scores at the team, division, or company level is not available through the API.
How quickly are data updates reflected in the API?
How quickly are data updates reflected in the API?
Updates to data in your account are processed and reflected in API responses within 20 minutes.
Related pages:
💬 Need help? Just reply with "Ask a Person" in a support conversation to speak with a Product Support Specialist.