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:

HS User ID: The unique ID used by Helpshift to track a user object that is exposed

OR

External User ID: If your organization has captured a unique user ID using the ‘loginWithIdentifier’ parameter, this ID can be used to identify the user to be redacted

OR

Email: If your organization has set an email address when creating Issues, or uses email support, then email can be used

OR

Issue: A single Issue can be used to identify a user – when an Issue is used, the user that reported the Issue will be redacted along with all other Issues by that same user
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 redaction request

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)

Example

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.

{:missing-fields (), :invalid-fields (hs_user_id)}
{:missing-fields (), :invalid-fields (:value :app_publish_id)}
eta Timestamp (ISO) Estimated Time of arrival, in ISO format
request Map Original request (against the response)

Sample response:

{
“status”: “created”,
“eta”: “timestamp”,
“hs_data_url”: “string”,
“url_valid_until”: “timestamp”
“request”: {
“property”: “email”,
“value”: “string”,
“app_publish_id”: “string”,
“external_redaction_id”: “string”
}
}