User Hub Bulk APIs
Introduction
The User Hub Bulk APIs can be used to import your end users' data into Helpshift, and export current end user data from Helpshift.
See POSTMAN Collection for details on the API endpoints. Use the Create Bulk Action Task API to create bulk
action tasks which will be processed asynchronously.
The data to be imported is specified as a payload in the API request. Each payload is a JSON array of maps, each map containing the data for a
single end user profile. There is a limit of 10000 payloads in a single request.
There are two ways of providing the payload -
Directly as a request parameter containing a JSON encoded string, using the x-www-form-urlencoded content type. This is suitable for smaller payloads.
curl --location 'https://api.helpshift.com/v2/domain/identity/bulk_actions' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'action=create_core_profiles' \
--data-urlencode 'payload=[{"identities":[{"uid":"uid-1"}],"last_country":"India","last_city":"Pune"},{"identities":[{"uid":"uid-2"}],"last_country":"Pakistan","last_city":"Karachi"},
{"identities":[{"uid":"uid-3"}],"last_country":"Sri Lanka","last_city":"Colombo"}]'
As a file, using the multipart/form-data content type. The file must be in JSONL format, with each line being a complete JSON map containing the data for a single record. This is recommended for larger payloads.
curl --location 'https://api.helpshift.com/v2/wabbit/identity/bulk_actions' \
--form 'action="update_core_profiles"' \
--form 'payload=@"data.jsonl"'
where data.jsonl has the following contents -
{"identities":[{"uid":"uid-1"}],"last_country":"India","last_city":"Pune"}
{"identities":[{"uid":"uid-2"}],"last_country":"Pakistan","last_city":"Karachi"}
{"identities":[{"uid":"uid-3"}],"last_country":"Sri Lanka","last_city":"Colombo"}
Usage
- Use the Create Bulk Action Task API to upload data into Helpshift, or request data export from Helpshift. In either case, the expected request format for each task type is listed below.
The API response will contain a
Task ID. - Using the Task ID, poll the Get Task Status API until the status is
completed. The values oferrorsand results can be used to determine if the task completed successfully, or with errors. - Use the Get Task Results and Get Task Errors APIs to retrieve data, or any errors.
Request Payloads
Create Core Profiles
Each entry in the payload should be a JSON map, containing one or more of the below fields. At least one identity is required. The response will contain the new core profile’s ID.
| Field | Details | Example |
|---|---|---|
| identities | Array of maps, each map contains an identity value which can be used to uniquely identify the end user. The map can also contain additional metadata as string key-value pairs, these metadata are stored as is, and not processed. The valid identity types are -
| [{"uid": "uid-1"}, |
| names | JSON map containing the end user’s name. The following components are supported, any combination can be provided -
| {"first_name": "Jane", |
| tags | JSON array of user tags. | [“vip”, “open_beta”, "streamer"] |
| custom_fields | JSON map of custom user fields. | {"region": "APAC", |
| full_privacy_enabled | Did the user enable full privacy? | false |
| last_country | End User’s country. Either ISO-3166 country name, or 2/3 letter ISO-3166 code. | India , IN , or IND |
| last_city | End User’s city. | Pune |
| age | End User’s Age. | 30 |
| lifetime_value | End User Lifetime Value | 1023.99 |
| user_persona | End User Persona | Streamer |
| user_vip_segment | End User VIP Segmentation | Diamond Class |
| user_support_status | End User Support Status | Active |
| accepted_t_and_c | Whether end user has accepted the terms and conditions. | true |
| preferred_language | ISO 639-1 language code | en |
| last_active_date | Timestamp based on Unix epoch (with milliseconds). | 1714627659283 |
Update Core Profiles
This payload is identical to the payload for create_core_profiles , with one additional field - core-profile-id , which is the ID of the core profile to be updated.
Any existing values will be overwritten with the values in the latest payload.
| Field | Details | Example |
|---|---|---|
| core-profile-id | Core Profile Publish ID | 1666311221477632 |
Update App Profiles
Each entry in the payload is a JSON map containing one or more of the following fields. The pid is required, as it identifies the end user app profile. The ID can be fetched using the Helpshift REST APIs, especially the Get Multiple Issues API.
| Field | Details | Example |
|---|---|---|
| pid | App Profile ID | domain_profile_4d0d12f4eb0cba8d4d4ace68187bccc7437e4df9 |
| custom_fields | JSON map of custom user fields (at app level). | {"region": "APAC", |
| user_persona | End User Persona | Streamer |
| user_paying_segment | End User Segmentation | Premium |
| user_vip_segment | End User VIP Segmentation | Diamond Class |
| user_level | End User Level | 455 |
| accepted_t_and_c | Whether end user has accepted the terms and conditions. | true |
| app_status | End User App Status | Unlocked |
| user_support_status | End User Support Status | Active |
| country | End User’s country Either ISO-3166 country name, or 2/3 letter ISO-3166 code. | India , IN , or IND |
| city | End User’s city. | Pune |
| language | ISO639-1 language code | en |
| app_rating | End User provided rating to app | 4 |
| lifetime_value | End User Lifetime Value | 1023.99 |
Get Core Profiles
Each entry in the payload is a JSON map containing just the core-profile-id of the core profile. The response will contain all the data for each core profile.
| Field | Details | Example |
|---|---|---|
| core-profile-id | Core Profile Publish ID | 1666311221477632 |
Get App Profiles
Each entry in the payload is a JSON map containing just the pid of the app profile. The response will contain all the data for each app profile.
| Field | Details | Example |
|---|---|---|
| pid | App Profile ID | domain_profile_4d0d12f4eb0cba8d4d4ace68187bccc7437e4df9 |