a) Initial Setup
The most straightforward method for incorporating structured data from external systems —be it a data lake, data storage system, or CRM— into Zurvey.io involves utilizing the standard RESTful API. The first step entails creating an API datastream on the home page through the API input tile.
Once the dataset is established, the API setup screen becomes accessible, presenting all essential information and, notably, enabling the configuration of the input data structure. This step is crucial as the system needs to anticipate the structure of incoming data. A dataset defines its structure through dimension definitions, similarly to columns in a database. Within this framework, you can establish dimension definitions (columns), which will subsequently be populated with data via the API.
For each dimension definition, you must specify the following attributes:
- Name: This identifier corresponds to the data on the dashboard. For categories, it serves as a filter, for text, it appears among the analyzed text columns, and for dates, it forms the basis for time series chart visualizations.
- Id: This identifier is used in API calls to distinguish data points.
- Type: Zurvey.io processes and visualizes various data types uniquely. Text data undergoes analysis by our NLP engines, category-type data functions as a dashboard filter, and NPS®, CSAT, and CES data generate dedicated charts and visualizations. Zurvey.io can handle seven types of input data: Text, Date, Category, Number, Id, NPS®, CSAT, and CES.
Adding new dimensions to the structure is facilitated by the "Add new row" button. The first table row exemplifies the "Submitted at" dimension, automatically populated by the system and containing the timestamp when the specific record was submitted through the API.
ID Naming Conventions: Only lowercase letters without accents and numbers are accepted. Please avoid spaces and special characters as well. Please do not add the same ID for multiple dimensions: otherwise only the first one will be populated with data.
b) Token Management
Zurvey.io employs tokens for request authorization, ensuring a secure and controlled data flow. Token management is conveniently accessible either directly from the API setup screen or through the settings page.
Upon creation, a token serves as the key for authorizing requests, following the HTTP Authorization Scheme: Bearer. Notably, tokens operate at the group level for authentication. To pinpoint the specific dataset in a request, utilize the corresponding dataset ID, conveniently available from the API setup screen.
For an in-depth understanding of our authorization process, please refer to our comprehensive API documentation.
c) Analysis Settings
Upon completing the dimension definition and establishing the data structure, the next step is to guide Zurvey.io on how to interpret your data effectively. This is where the Analysis Settings come into play.
Within this section, you have the flexibility to:
- Change the name of your API dataset: tailor the dataset name to enhance clarity and relevance on the Zurvey.io platform.
- Modify the analysis language: specify the language for text data analysis, ensuring accurate and meaningful insights.
- Adjust accented character handling: customize how Zurvey.io processes accented characters in your data.
- Manage lowercase characters: define preferences for handling lowercase characters in your dataset.
- Toggle automatic topic recognition: enable or disable the automatic recognition of topics based on your analytical needs.
- Modify text splitting style: tailor the style of text splitting to align with your data's characteristics.
d) Custom Label Analysis
To elevate the precision of text analysis, Zurvey.io provides the ability to apply Custom Labels to text dimensions. To explore and assign available custom labels to the text dimension, simply click on the tag icon located next to the dimension type selector dropdown.
For a deeper understanding of Custom Labels and their integration into our text analysis methodology, we recommend referring to our dedicated documentation.
e) Editing & Reanalysis
If you need to make adjustments to your API datastream, such as:
- Adding new data dimensions
- Modifying the name or type of an existing dimension (available only if no data has been recorded for that specific dimension)
- Deleting an existing dimension (available only if no data has been recorded for that specific dimension)
- Changing Analysis Settings
- Modifying assigned Custom Labels
You can edit your previously saved and populated dataset and reanalyze the already processed data.
Upon making your changes and clicking the "Save Settings" button at the bottom, a popup will prompt you to decide whether you would like to apply your changes only to the new incoming data or reanalyze the entire dataset.
If you've modified Analysis Settings, including analysis language, lowercase character handling, accented character handling, or text splitting style, you will have the ability to choose whether to apply changes for new data only, reanalyze the entire dataset, or reanalyze data from a specific set date (with the default set date being the creation date of the dataset).
f) API Documentation
For comprehensive guidance on how to insert records into an API dataset, along with details on the required format, please refer to our API documentation. This resource serves as a comprehensive reference, providing all the necessary information for integration and data submission.