Overview

The Data Export API enables you to automate the submission of data export requests and retrieve the results asynchronously. This approach ensures that large datasets can be processed efficiently without causing delays in the client application.

Authorization

To use the Data Export API, you need an API key. Please reach out to your customer success representative to obtain your API key for data deletion requests. This API key should be included in every request as a value for the api-key header.

API Endpoints

SubmitAsync

Endpoint: POST /external/v1/async/submit

This endpoint facilitates the submission of data export requests, providing a reference for the export in the response. This reference can then be utilized with the fetch API to retrieve the exported data at a later time.

The export request allows users to specify the data to be exported using various filtering options. Below are the details of the request model.

Request Message:

Export Request

Field	Type	IsRequired	Comment
listRecords	ListRecordsRequest	Yes	Specifies what records to fetch.
pageSize	Int	Yes	The maximum number of records is to be contained in a single file in the response. i.e if the listRecords criteria match the 14k records, and pageSize is 5k, the response will contain 3 files.

ListRecordsRequest

Field	Type	IsRequired	Comment
filter	FilterQuery	No	Filters to narrow down the data. This is similar to filtering in the data using Enterpret query builder.
timerange	TimeRange	Yes	The time range for which the data is to be fetched.

FilterQuery

Please note that only of the filter, or operation field can be provided as part of this.

Field	Type	IsRequired	Comment
filter	Filter	No	An individual filter, like filtering on metadata, labels, etc.
operation	FilterQueryOperation	No	Multiple filters tied with operations like, OR, AND, etc.

FilterQueryOperation

Field	Type	IsRequired	Comment
op	String	Yes	Possible values are `OR`, or `AND`.
params	[]FilterQuery	Yes	List of filter queries. This allows building in nested operations by creating a recursive relation between FilterQuery and FilterQueryOperation.

Filter

Please note that only one of the following fields can be populated as part of a single filter clause.

Field	Type	IsRequired	Comment
metadata	MetadataFilter	No	Filter based on metadata.
languageISO6393	String	No	Filter feedback from a particular language.
source	string		Filter feedback from a particular source.
hasLabel	HasLabelFilter	No	Filter feedback that has a Keyword, Reason, or Sentiment present on it.

MetadataFilter

Field	Type	IsRequired	Comment
key	String	Yes	Metadata Key to filter on.
value	Value	Yes	Value for the key.
op	String	No	Possible values are `EQ`, `GT`, `LT`, `GTE`, `LTE`, where `EQ` is the default operator.

HasLabelFilter

Please note that only one of the following fields can be populated.

Field	Type	IsRequired	Comment
aspect	Boolean	No	Filter records with keywords.
reason	Boolean	No	Filter records with reasons.
sentiment	Boolean	No	Filter records with sentiment.

TimeRange

Either provide the startTime and the endTime or provide the relative time.

Field	Type	IsRequired	Comment
startTime	int64	No	Start time in epoch seconds.
endTime	int64	No	Endtime in epoch seconds.
relative	RelativeTimeRange	No	Relative time.

RelativeTimeRange

Field	Type	IsRequired	Comment
value	int64	Yes
unit	String	Yes	Possible values are, `Hour`, `Day`, `Week`, `Month`, `Year`.

Example Requests

To submit a data export request, send a POST request to /external/v1/async/submit with the following JSON payload:

{
  "pageSize": 100,
  "request": {
    "listRecords": {
      // Your listRecords request payload
    }
  }
}

Include the API key in the headers:

api-key: YOUR_API_KEY

Request to get last 30 days of data from ZendeskSupport or Twitter.

{
  "listRecords": {
    "filter": {
      "operation": {
        "op": "OR",
        "params": [
          {
            "filter": {
              "source": "ZendeskSupport"
            }
          },
          {
            "filter": {
              "source": "Twitter"
            }
          }
        ]
      }
    },
    "timerange": {
      "relative": {
        "unit": "Day",
        "value": "30"
      }
    }
  },
  "pageSize": "5000"
}

Request to get the last 2 months' data from ZendeskSupport or Twitter, only if it has a Reason prediction on it.

{
  "listRecords": {
    "filter": {
      "operation": {
        "op": "AND",
        "params": [
          {
            "filter": {
              "hasLabel": {
                "reason": true
              }
            }
          },
          {
            "operation": {
              "op": "OR",
              "params": [
                {
                  "filter": {
                    "source": "ZendeskSupport"
                  }
                },
                {
                  "filter": {
                    "source": "Twitter"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    "timerange": {
      "relative": {
        "unit": "Month",
        "value": "2"
      }
    }
  },
  "pageSize": "5000"
}

Response Message:

Field	Type	IsRequired	Comment
queryID	String	Yes	Reference for the submitted query

Example Response

{
    "queryID": "async-avi5jg"
}

FetchAsync

Fetches the results of an asynchronous data export request created with the previous API.

Endpoint: POST /external/v1/async/fetch

Request Message:

Field	Type	IsRequired	Comment
queryID	String	Yes	QueryID that we received as the response from the previous API.

Example Request

To fetch the results of a previously submitted data export request, send a POST request to /external/v1/async/fetch with the following JSON payload:

{
  "queryID": "your-query-id"
}

Include the API key in the headers:

api-key: YOUR_API_KEY

e.g

{
    "queryID": "async-avi5jg"
}

Response Message

If the export is in progress, the API returns an empty JSON, with a 200 Status Code. Once the export request is completed, it contains the following response.

Field	Type	IsRequired	Comment
responseFiles	[]String	Yes	List of files containing the feedback data. Do note that the link to these files expires in a few hours, so process the content before that.

The file content is JSON, which has the following schema.

File Content Schema

Field	Type	IsRequired	Comment
records	[]FeedbackRecord	Yes	List of feedback records.

FeedbackRecord

Field	Type	IsRequired	Comment
id	String	Yes	ID of the Record
source	String	Yes	Source of the Record
orgID	String	Yes	OrgID that record belongs to.
type	String	Yes	`RecordTypeReview`, `RecordTypeConversation`, `RecordTypeSurvey`, `RecordTypeForumConversationThread`
sourceTimestamp	int	Yes	sourceTimestamp is timestamp of the feedback as reported by the source
ingestedAt	int	Yes	timestamp when feedback was ingested to Enterpret.
languages	[]Language	Yes	languages detected in the original feedback.
originRecordID	String	Yes	Unique identifier for the records in the source system.
predictions	[]Prediction	No	Ids of the predictions for this Feedback Records. We can resolve the label names and other details for these using the label API discussed later.
summary	[]String	No	Summaries for the feedback record.
text	TextContent	No	Present if feedback is of type review.
conversation	ConversationContent	No	Present if feedback is of type conversation, or forum thread.
survey	SurveyContent	No	Present if the feedback is of type survey.

TextContent

Field	Type	IsRequired	Comment
text	String	Yes	Text of feedback.
textEn	String	No	Text of feedback in English, if the original feedback is in non-english.

ConversationContent

Field	Type	IsRequired	Comment
conversation	Conversation	Yes	content of the feedback.
conversationEn	Conversation	No	content of feedback in English, if the original feedback is in non-English.

Conversation

Field	Type	IsRequired	Comment
msgs	[]ConversationMessage	Yes	msgs in the conversation

ConversationMessage

Field	Type	IsRequired	Comment
text	String	Yes	content of the feedback.
actor	String	Yes	`user`, `agent`, `bot`
actorID	String	No	Id of the actor.

SurveyContent

Field	Type	IsRequired	Comment
surveyResponse	SurveyResponse	Yes	content of the feedback.
surveyResponseEn	SurveyResponse	Yes	content of the feedback in English, if the original feedback is in non-English.

SurveyResponse

Field	Type	IsRequired	Comment
responses	[]SurveyQA	Yes	list of question answer in the survey

SurveyQA

Field	Type	IsRequired	Comment
question	String	Yes
answer	String	Yes
selectedOptions	[]String	No	for multi-select questions.

Example File Content

{
  "records": [
    {
      "id": "f742cf1a-382c-5af1-9f3c-4989c40c95d1",
      "source": "Playstore",
      "orgID": "573c9d74-bdc4-4c6d-bd40-3465658ab47b",
      "type": "RecordTypeReview",
      "metadata": {
        "keyValues": {
          "App id": {
            "s": [
              "us.zoom.videomeetings"
            ]
          },
          "Id": {
            "s": [
              "b2578def-37c4-4afd-a763-bbc81a11a1cc"
            ]
          },
          "Language code": {
            "s": [
              "bg"
            ]
          },
          "Language name": {
            "s": [
              "Bulgarian"
            ]
          },
          "Rating": {
            "n": [
              1
            ]
          },
          "Reviewer": {
            "s": [
              "owilli samuel"
            ]
          },
          "Timestamp": {
            "n": [
              1721302100
            ]
          },
          "Useful": {
            "n": [
              0
            ]
          },
          "Version": {
            "s": [
              "6.0.12.22225"
            ]
          }
        }
      },
      "sourceTimestamp": "1721302089",
      "ingestedAt": "1721389257",
      "languages": [
        {
          "iso6393": "eng",
          "iso6391": "en",
          "source": "detected"
        }
      ],
      "predictions": [
        {
          "labelID": "b818b657-3d0f-4113-bb54-f4bf8a2bbdfa",
          "sentiment": {}
        },
        {
          "labelID": "f7794882-b8cc-42fa-afd3-8159cf618b21",
          "reason": {
            "units": [
              {
                "confidence": 1.0000001
              }
            ]
          }
        }
      ],
      "summary": [
        "The user has an extremely positive experience with Zoom, but does not provide specific details.",
        "happy with zoom::praise"
      ],
      "text": {
        "text": "Extremely good."
      }
    },
    {
      "id": "9c014e6d-475e-5589-bca6-3f5dd96f45e7",
      "source": "Playstore",
      "orgID": "573c9d74-bdc4-4c6d-bd40-3465658ab47b",
      "type": "RecordTypeReview",
      "metadata": {
        "keyValues": {
          "App id": {
            "s": [
              "us.zoom.videomeetings"
            ]
          },
          "Id": {
            "s": [
              "9d23cbf4-e8fd-4d36-8d78-45dd4915da75"
            ]
          },
          "Language code": {
            "s": [
              "uk"
            ]
          },
          "Language name": {
            "s": [
              "Ukrainian"
            ]
          },
          "Rating": {
            "n": [
              5
            ]
          },
          "Reviewer": {
            "s": [
              "Haribhan Bhatt"
            ]
          },
          "Timestamp": {
            "n": [
              1721300500
            ]
          },
          "Useful": {
            "n": [
              0
            ]
          },
          "Version": {
            "s": [
              "6.1.1.22710"
            ]
          }
        }
      },
      "sourceTimestamp": "1721300532",
      "ingestedAt": "1721389333",
      "languages": [
        {
          "iso6393": "eng",
          "iso6391": "en",
          "source": "detected"
        }
      ],
      "text": {
        "text": "Nice"
      }
    },
    {
      "id": "acfc9e64-60f4-5098-9617-ffb1259b9d1b",
      "source": "Playstore",
      "orgID": "573c9d74-bdc4-4c6d-bd40-3465658ab47b",
      "type": "RecordTypeReview",
      "metadata": {
        "keyValues": {
          "App id": {
            "s": [
              "us.zoom.videomeetings"
            ]
          },
          "Id": {
            "s": [
              "577b0588-ff98-439b-8210-2bdcb6ad7bd9"
            ]
          },
          "Language code": {
            "s": [
              "vi"
            ]
          },
          "Language name": {
            "s": [
              "Vietnamese"
            ]
          },
          "Rating": {
            "n": [
              2
            ]
          },
          "Reviewer": {
            "s": [
              "Vivek Kamble"
            ]
          },
          "Timestamp": {
            "n": [
              1721300500
            ]
          },
          "Useful": {
            "n": [
              0
            ]
          },
          "Version": {
            "s": [
              "6.1.1.22710"
            ]
          }
        }
      },
      "sourceTimestamp": "1721300422",
      "ingestedAt": "1721389333",
      "languages": [
        {
          "iso6393": "eng",
          "iso6391": "en",
          "source": "detected"
        }
      ],
      "predictions": [
        {
          "labelID": "e9c9fc3b-093b-47b9-8432-534d40558e88",
          "reason": {
            "units": [
              {
                "confidence": 0.9706277
              }
            ]
          }
        },
        {
          "labelID": "b21c5a63-db73-4d13-b4d4-3c30b85029d2",
          "sentiment": {}
        }
      ],
      "summary": [
        "The user is dissatisfied with the Zoom app's performance on Android mobiles.",
        "issue with zoom app performance on android mobiles::issue"
      ],
      "text": {
        "text": "Poor app to use on android mobiles"
      }
    }
  ]
}

Labels API

https://api.enterpret.com/export/external/v1/labels/<labelid>

Response:

{
    "label": {
        "id": "88aea2c2-3fb6-489a-99b9-72adddc78e6f",
        "displayName": "Issue With Uploading Documents",
        "type": "REASON",
        "description": "Customers face issues with the document upload process, encountering problems with the file upload feature provided by Enterpret Inc.",
        "createdAt": "1699632396",
        "isVisible": true,
        "metadata": {
            "reason": {
                "sentiment": "NEUTRAL",
                "representativeSentences": [
                    "issue uploading documents",
                    "issue with file upload feature"
                ],
                "type": "MANUALLY_DEFINED"
            }
        }
    }
}

Troubleshooting

If you encounter any issues while using the Data Export API, please refer to the following common problems and solutions:

Invalid API Key: Ensure that you have included the correct API key in the api-key header.
Invalid Request: Make sure all required fields are included in your request payload.
Server Errors: If you receive a server error, contact Enterpret support for assistance.

For further assistance, please reach out to Enterpret support or your customer success representative.

Custom Webhook

File Upload: CSV data on Enterpret

Census Integration

Syncing Users and Accounts

User Privacy API