Skip to main content
All CollectionsAccount Admin HubIntegrations & APISurvey API
Survey API
Survey API

Easily retrieve raw data from Culture Amp surveys via the Survey API, with metadata, questions, and responses available for analysis.

Jessie Walsh avatar
Written by Jessie Walsh
Updated over a month ago

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 rdeEnabled field which must have the value true returned against a given survey for its data to be accessible via other survey API endpoints.

  • If a particular survey returns a false value 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:

  1. Engagement

  2. Effectiveness

  3. Lifecycle

Workflow

All survey workflows are in scope of data served.

Includes:

  1. Continuous

  2. Snapshot

  3. Three sixty

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

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:

  1. launchedAt

  2. closedAt

  3. communicatedClosedAt

  4. createdAt

  5. updatedAt

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

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?

No, confidential survey data cannot be accessed through the API.

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?

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.

Related Articles
Understanding raw data extracts
How to download a raw data extract
Culture Amp API
Reporting API
How to enable Raw Data on your Survey
Did this answer your question?