Thematic API - Uploading Data

Note: This article assumes that you have an ACCESS_TOKEN ready for use. The examples in the code below will include where the word ACCESS_TOKEN needs to be replaced with your token.

Note 2: Please see the note on regions at the bottom.

These instructions include examples using curl in bash notation,  if you are using a different terminal there may be some modification necessary to make the commands work. The commands also assume you are using the US data center. If this isn't the case the examples will need to be modified with the correct base url.

Organization Identifiers

Every account in Thematic has a unique identifier. This identifier will need to be used to identify which account a call is being made about. This is because the same user could have access to multiple organizations. An identifier looks like "sda29969"

Getting your organization identifier

The following command will return a list of organizations you have access to along with their details.

curl --request GET \
--url 'https://client.getthematic.com/api/organizations' \
--header 'Authorization: bearer ACCESS_TOKEN'<br>

This will return a list of organizations you have access to along with their identifiers (and some permissions information). A simplified view of the data returned is shown below:

{
    "data": [
        {
            "currentUserCan": [
                "read:organization"
            ],
            "displayId": "sdt38517",
            "name": "Sales Demo – Twitch",
            "status": "normal"
        },
        {
            "currentUserCan": [
                "read:organization"
            ],
            "displayId": "sda29969",
            "name": "Sales Demo – Airlines",
            "status": "normal"
        }
    ],
    "status": "success"
}<br>

The field needed is 'displayId', so the identifier for "Sales Demo – Airlines" is "sda29969"

Dataset Identifiers

Every dataset has an identifier (called a survey identifier in the API documentation). This identifier is necessary to identify which data set an upload is for. A survey identifier is a number that looks like 217

Getting your dataset identifier

To get a dataset identifier you will need the organization identifier, so please make sure to follow the instructions above first.

The call to list the datasets (surveys) you have access to within an organization is as follows:

curl --request GET \
--url 'https://client.getthematic.com/api/surveys?organization=ORGANIZATION_IDENTIFIER' \
--header 'Authorization: bearer ACCESS_TOKEN'<br>

Fields you will need to replace:

  • ORGANIZATION_IDENTIFIER: The identifier for your organization found above
  • ACCESS_TOKEN: Your access token

This will return a list of datasets (surveys) which includes their identifiers needed to make further calls. A simplified view of the data returned is shown below

{
    "data": [
        {
            "currentUserCan": [
                "read:survey"
            ],
            "dataSourceIntegration": null,
            "dataStatus": "READY",
            "dataVolume": 0,
            "hasDraftThemes": false,
            "id": "217",
            "includeInMetrics": true,
            "isPreview": false,
            "lastUpdated": "never",
            "manualUploadAllowed": true,
            "name": "Airlines Customer Feedback",
            "order": 0,
            "orgId": "sda29969",
            "results": [],
            "surveyStatus": "normal",
            "views": []
        }
    ],
    "status": "success"
}<br>

The field needed is 'id' so the identifier for "Airlines Customer Feedback" is "217"

Uploading data

Once you have a dataset (survey) identifier, uploading a file is possible. The file should be a csv or xlsx file (with all data in the first sheet) that follows the format of previous uploads. If you are in doubt as to what format this should be, please reach out to your customer success agent who will be able to help you.

Presuming the file is called 'upload.csv' and is in the same directory as where you are making the calls, the appropriate command would be:

curl --request POST \
--url "https://client.getthematic.com/api/survey/SURVEY_IDENTIFIER/upload" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--form "file=@upload.csv"<br>

Fields you will need to replace:

  • SURVEY_IDENTIFIER: The identifier for your dataset (survey) found above
  • ACCESS_TOKEN: Your access token

Uploading and processing data is asynchronous, this means that what is returned is a job identifier that can be used to track the progress of the data as it is processed. An example of what is returned from this command is as follows:

{
    "data": {
        "callback_url": "",
        "job_status": "queued",
        "job_type": "newdata",
        "upload_id": "fae644a2-2a18-4fa2-8912-a20e69294924"
    },
    "status": "success"
}<br>

From this data we can see that the data will be treated as "newdata" (to be added to existing data), is "queued" for processing and has an "upload_id" of "fae644a2-2a18-4fa2-8912-a20e69294924" which can be used to track the progress of the upload.

Tracking progress of an upload

With an upload identifier you can track the progress of an upload and check if it succeeded or failed using both the survey and upload identifiers:

curl --request GET \
--url "https://client.getthematic.com/api/survey/SURVEY_IDENTIFIER/upload/UPLOAD_IDENTIFIER" \
--header 'Authorization: bearer ACCESS_TOKEN'<br>

Fields you will need to replace:

  • SURVEY_IDENTIFIER: The identifier for your dataset (survey) found above
  • UPLOAD_IDENTIFIER: The identifier for the upload, returned when the file was uploaded.
  • ACCESS_TOKEN: Your access token

This will return details about the upload, including when it was uploaded and what the current status is.

{
    "data": {
        "callback_url": "",
        "created": "2021-05-16 22:11:18.482655",
        "created_by": "nathan@getthematic.com",
        "delta_job": null,
        "filter_string": null,
        "full_job": null,
        "id": "fae644a2-2a18-4fa2-8912-a20e69294924",
        "job_type": "ProcessingJobType.newdata",
        "original_filename": "upload.csv",
        "processed": "None",
        "review_job": null,
        "status": "ProcessingJobStatus.processing"
    },
    "status": "success"
}<br>

The status field can be used to track if the job succeeded or not.

What does it mean if an upload succeeds?

It means that the data was accepted, and has attempted to be merged with the data previously provided. This includes checking that the number of columns are correct and the types of special columns such as dates and scores. However it is possible for data to succeed and not be correct. For example if columns are transposed and what should be the comment column is instead filled with numbers, or blank strings.

What does it mean if an upload errors?

If an upload errors then our support will be notified and will help track down the cause of the error.

A note on regions

Thematic supports different geographical regions to ensure data sovereignty. When making calls to the Thematic API (or viewing documentation) it is important to look at the correct region and use the correct url. The regions Thematic currently supports are:

It is possible to see which region you are in by looking at the URL while logged into Thematic's Client Portal.