Setting up the Data Export API

In order to set up and use the Data Export API from Survicate, there are some prerequisites that must be fulfilled.

Prerequisites

1. Survicate Account: First and foremost, you must have an account with Survicate. If you don't already have one, you can create your account at panel.survicate.com. Alternatively, you can join your company's account if you've received an invitation from a colleague.

2. Proper Subscription: Secondly, to use the Data Export API, your Survicate account must be subscribed to a plan that includes API access. Please note that without a valid subscription, any API requests will result in an error response. Please review Survicate's plans and make sure you're subscribed to the one that best suits your needs and includes API access.

Endpoints

To connect to the Data Export API endpoints, use the base URL:

Authentication

Once you've fulfilled the prerequisites, you're ready to start using the Data Export API.

To authenticate yourself and begin your data exports, you'll need your API key. This key can be found in the Surviacate panel, specifically under the "Surveys Settings" tab, inside the "Access Keys" section.

Once you have your API key, you'll need to provide it for authentication purposes. The API key should be included in the Authorization header of your API requests. The format for this should be Basic {{apiKey}}. Remember to replace {{apiKey}} with your actual API key when making requests.

That's it! With your account set up, the right subscription, and your API key, you're ready to start using Survicate's Data Export API. Enjoy your journey in capturing and analyzing user feedback for better insights and business decisions!

Pagination

All list endpoints in the Data Export API are paginated. There are no page numbers - instead of asking for page=2, you follow the link the API gives you in each response.

Result order and the date range

Results are ordered from the latest to the oldest record. The start and end parameters mark the two ends of that range, in that order:

• start is the newer bound and the point the page starts from. Records collected at or before it are included.
• end is the older bound. Records collected at or after it are included.

Both bounds are inclusive, and because of the ordering start must be later than end. Timestamps use ISO 8601 with microseconds, for example 2024-08-31T23:59:59.000000Z.

So to export everything collected between August 26 and August 31, 2024, the two timestamps are swapped compared to what you might expect:

Page size

items_per_page accepts a value between 1 and 100. It is optional - if you omit it, the API applies its own default page size.

Following next_url

Every list response contains a pagination_data object:

• has_more tells you whether another page exists.
• next_url is always a path relative to the base URL https://data-api.survicate.com/v2, never an absolute URL. Prepend the base URL and request the path as-is, without rebuilding the query string yourself.

Under the hood next_url moves the start timestamp back to where the previous page ended, keeping your original end and any filters intact. Because Survicate builds that link for you, you don't need to work out the next boundary or worry about skipping records.

A complete walkthrough

Request 1 - the first page of responses collected between August 26 and August 31, 2024, 100 at a time:

Request 2 - take next_url, prepend the base URL, and call it:

Request 3 - keep going until has_more is false. That response is the last page; stop there even if a next_url is present:

In code, the loop is simply: call the endpoint, process data, and while has_more is true, request https://data-api.survicate.com/v2 + next_url again.

Attributes

Responses and respondents can carry attributes: name/value pairs such as order_id, store or state.

Every attribute is one you passed to Survicate yourself - through the JavaScript API, a mobile SDK, an integration, or the survey link. The names you get back are the names you set, and the values are always returned as strings. Survicate does not add reserved or native attributes of its own, so there is no reserved vs. custom distinction to handle: if a field like survey_type shows up in the attributes array, it is there because it was sent to Survicate.

Fields that Survicate always returns - uuid, respondent_uuid, collected_at, url, device_type, operating_system, language and questions - are top-level properties of a response, not attributes. See Response for the full schema.

Rate limiting

Survicate implements a set of rate limiting measures designed to protect our infrastructure from overwhelming traffic spikes. Adhering to these limits ensures that our services remain stable and available for all users. The rate limits are as follows:

• Concurrent Request Limit: You can make up to 5 concurrent (simultaneous) API requests. To avoid breaching this limit, design your system to wait for a response from your current request before initiating another. This mechanism helps ensure that your operations do not overload the system with multiple simultaneous demands.
• Workspace Request Limit: There's a cap of 1000 requests per minute for each workspace. This limit safeguards the system from an excessive number of requests within a short timeframe, enabling the fair and efficient use of our resources across all users.

In the event that you exceed any of these limits, our system will respond with a 429 Too Many Requests status code. This code serves as a signal that your operation has been temporarily blocked due to excessive requests. It is, therefore, important to manage your requests to stay within these bounds, ensuring smooth operations and uninterrupted API access.

If you have any questions or require assistance, our support team is ready to help. Please use the live chat feature located in the bottom right corner of your screen. We're here to ensure your experience is smooth and efficient.