Personal data in Helpshift includes all of the Issue details and user information associated with the end user that is stored on Helpshift’s servers. Helpshift provides a set of REST APIs that you can use to automatically create data portability requests per GDPR requirements. Data portability requests are processed on a weekly basis.
To initiate data portability requests, you can use the REST /hs-data API. When setting up the API call, you will be prompted to provide information about the user. Once the request is created, Helpshift will automatically schedule a periodic batch process that will collect the requested data.
You can periodically use the /hs-data/status API to monitor the status of your pending data portability requests. When the request has been completed, you will receive a time-sensitive link to the data in a compressed format.
To provide flexibility, users can be identified via a variety of different methods, as defined in the table below.
| User identification | What information is returned? |
|---|---|
| A user can be identified as follows: | The user’s profile information along with a set of Issues created by the user. The Issue info includes the messages, attachments, Custom Issue Fields and more. |
Once you have a set of users identified for data portability requests, you can use the following REST APIs to create and monitor these redaction requests. Please see our Getting Started page for our REST APIs to learn more.
PART 1: Creating Data Portability Requests (POST /hs-data)
API: POST /hs-data
The POST /hs-data API can be used to submit a set of data portability requests by passing in the ‘requests’ object in a JSON format as follows:
| Parameter | Type | Required? |
|---|---|---|
| requests | Array of export requests (see below) | Yes |
The requests object contains the following properties:
Property | Type | Required? | Description |
|---|---|---|---|
property | String | Yes | “user_id” OR “hs_user_id” OR “issue_id” OR “email” to indicate what identity will be provided |
value | String | Yes | The actual identifier (User ID, HS User ID, Issue ID or Email) used to identify the user |
app_publish_id | App ID | Yes | The app that the portability request will take place for – this must match the app for the user or Issue |
external_publish_id | String | No | An optional external tracking ID that can be set when creating the data portability request |
password | String | No | (Optional) The output data will be encrypted using the given password. The password must be 8 to 64 characters in length. |
Example
The app information you need to pass is the app_publish_id. The app publish ID can be found on your Settings > App Settings page (per the screenshot below)
Sample CURL request:
curl -X POST
-H “Authorization: Basic ########”
-H “Cache-Control: no-cache”
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW”
-F “requests=[ { “property”: “issue_id”%2C “value”: “270”%2C “app_publish_id”: “12”%2C “external_request_id”: “my_portdb_id_123″ } ]”
“https://api.helpshift.com/v1/ashbys/hs-data/”
Response:
The following will be returned from the POST request:
| Parameter | Type |
|---|---|
| status | HTTP status codes 200, 404, etc. Returns 200 for request successfully processed, 404 for failure to process the entire request. |
| body | Array of export request responses (below) |
Response body:
The structure of the individual response is given in the table below:
| Parameter | Type | Description |
|---|---|---|
| hs_request_id | ID | A unique ID used to track the portability request |
| success | T/F | An indicator for whether or not the creation of the portability request was a success |
| external_request_id | ID | The external ID given in the request for tracking |
| eta | Date | The estimated date when the job may complete |
| reason | String | If there is a failure to create a request, this is the reason why that request failed – user id id is invalid |
PART 2: Confirming the Portability Request Status
API: GET /hs-data/status
The GET /hs-data/status API will return a set of existing portability requests along with the current status of each request.
Filters:
The GET /hs-data/status API are used to identify specific portability requests. At least one of the following filters is required.
| Filter | Use |
|---|---|
| /hs-data/status?external_request_id=value | Uses an external request ID to know the status of portability requests |
| /hs-data/status?hs_request_id=value | Uses an hs request ID to know the status of portability requests |
Response:
Please note that the body can contain one or more responses.
| Parameter | Type |
|---|---|
| status | HTTP status codes 200, 404, etc. Returns 200 for a request that was successfully processed; returns 404 a request that was not successfully processed. |
| body | Array of export request responses (below) |
Response body:
The structure of the individual response is given in the table below:
| Parameter | Type | Description |
|---|---|---|
| hs_request_id | ID | Uniquely generated request ID |
| status | String | Indicates the request processing state |
| external_request_id | ID | The site’s tracking ID given in the request |
| hs_data_url | String | The URL to download the data |
| url_valid_until | Timestamp (ISO) | Estimate of the time until the download of the URL is valid. |
| reason | String | Reason for failure – for example, if the user ID or Issue ID is incorrect, then this will return a JSON list of any required fields that are missing, and a list of any invalid format fields. |
| eta | Timestamp (ISO) | Estimated Time of arrival, in ISO format |
| request | Map | Original request (against the response) |
| encrypted_zip? | Boolean | Indicates whether the ZIP file is password-protected or not. Note: This field will be available only when value of “status” is “Done”. |
Sample response:
{
“status”: “created”,
“eta”: “timestamp”,
“hs_data_url”: “string”,
“url_valid_until”: “timestamp”,
“encrypted_zip?” : “boolean”,
“request”: {
“property”: “email”,
“value”: “string”,
“app_publish_id”: “string”,
“external_redaction_id”: “string”
}
}